flow-comet 1.5.0-rc.3

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 (59) hide show
  1. package/.flow-comet/rules/flow-comet-orchestration.md +13 -0
  2. package/.flow-comet/skills/flow-comet/GUIDANCE.md +196 -0
  3. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -0
  4. package/.flow-comet/skills/flow-comet/SKILL.md +196 -0
  5. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +19 -0
  6. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +115 -0
  7. package/.flow-comet/skills/flow-comet/reference/authoring-lanes.json +33 -0
  8. package/.flow-comet/skills/flow-comet/reference/composition-report.md +65 -0
  9. package/.flow-comet/skills/flow-comet/reference/decision-points.md +64 -0
  10. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +30 -0
  11. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +169 -0
  12. package/.flow-comet/skills/flow-comet/reference/init-detection.md +58 -0
  13. package/.flow-comet/skills/flow-comet/reference/recovery.md +20 -0
  14. package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +661 -0
  15. package/.flow-comet/skills/flow-comet/reference/skill-review.md +13 -0
  16. package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +7 -0
  17. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +681 -0
  18. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +52 -0
  19. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +61 -0
  20. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +909 -0
  21. package/.flow-comet/skills/flow-comet/scripts/comet-plan.mjs +2 -0
  22. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +312 -0
  23. package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +136 -0
  24. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +7331 -0
  25. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +376 -0
  26. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +230 -0
  27. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +99 -0
  28. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +4017 -0
  29. package/.flow-comet/skills/flow-comet/scripts/task-parsing.mjs +28 -0
  30. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +2396 -0
  31. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +378 -0
  32. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +1263 -0
  33. package/.flow-comet/skills/flow-comet-archive/SKILL.md +195 -0
  34. package/.flow-comet/skills/flow-comet-change/SKILL.md +29 -0
  35. package/.flow-comet/skills/flow-comet-compose/SKILL.md +249 -0
  36. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +23 -0
  37. package/.flow-comet/skills/flow-comet-design/SKILL.md +161 -0
  38. package/.flow-comet/skills/flow-comet-dev/SKILL.md +51 -0
  39. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +26 -0
  40. package/.flow-comet/skills/flow-comet-execute/SKILL.md +182 -0
  41. package/.flow-comet/skills/flow-comet-health/SKILL.md +31 -0
  42. package/.flow-comet/skills/flow-comet-integration/SKILL.md +45 -0
  43. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +36 -0
  44. package/.flow-comet/skills/flow-comet-open/SKILL.md +161 -0
  45. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +33 -0
  46. package/.flow-comet/skills/flow-comet-plan/SKILL.md +169 -0
  47. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +27 -0
  48. package/.flow-comet/skills/flow-comet-review/SKILL.md +204 -0
  49. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +29 -0
  50. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +214 -0
  51. package/.flow-comet/skills/flow-comet-task/SKILL.md +33 -0
  52. package/.flow-comet/skills/flow-comet-test/SKILL.md +41 -0
  53. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +26 -0
  54. package/.flow-comet/skills/flow-comet-verify/SKILL.md +164 -0
  55. package/LICENSE +21 -0
  56. package/README.md +255 -0
  57. package/package.json +27 -0
  58. package/scripts/dsh-bridge.mjs +461 -0
  59. package/scripts/prepare-env.mjs +1526 -0
@@ -0,0 +1,195 @@
1
+ ---
2
+ name: flow-comet-archive
3
+ description: "Use only when explicitly invoked as /flow-comet-archive or routed by the flow-comet entry/runtime to the archive Node; complete Archive for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
4
+ ---
5
+
6
+ # Archive
7
+
8
+ ## Node Goal
9
+
10
+ Complete the `archive` Node for `flow-comet`.
11
+
12
+ Responsibility: LESSONS 提名 + 归档到 .specs/archive/ + CHANGELOG 更新。
13
+
14
+ This node finalizes a completed change by extracting reusable lessons from the development process, archiving the change artifacts, and updating the project changelog. It ensures that hard-won knowledge (debugging > 30min, cross-task applicability, 6-month retry probability) is preserved in the project-level LESSONS.md, while change-specific artifacts are moved to the archive for future reference. This is the final node in the flow-comet workflow.
15
+
16
+ ## Guidance
17
+
18
+ ### Prerequisites
19
+
20
+ - `.specs/<change-id>/UAT.md` must exist with all items passed (from verify node).
21
+ - All `*-SUMMARY.md` files must exist for completed tasks.
22
+ - `.specs/<change-id>/REVIEW.md` must exist with all Critical resolved.
23
+ - The archive operation is irreversible (file move) — requires user confirmation before execution.
24
+
25
+ ### Steps
26
+
27
+ 1. **Scan SUMMARY.md files for lessons**: Read all `<task-id>-SUMMARY.md` files in `.specs/<change-id>/`. Focus on "decisions and deviations" sections. Also check any remaining `<task-id>-PROGRESS.md` "excluded solutions" sections.
28
+
29
+ 2. **Apply nomination criteria**: For each potential lesson:
30
+ - Debugging/trial-and-error took > 30 minutes -> nominate.
31
+ - Error is not task-specific, other tasks would hit it too -> nominate.
32
+ - Reasonable probability of retry within 6 months -> nominate.
33
+ - Otherwise do not nominate (avoid pollution of LESSONS.md).
34
+
35
+ 3. **Add qualifying lessons to LESSONS.md**: For each nominated lesson:
36
+ - Assign next `L-NNN` number (continuing from existing).
37
+ - Fill required fields: label, keywords, applicable tech stack, status (active).
38
+ - Save to `.specs/LESSONS.md` — 新条目编号 = 当前最大编号 + 1,插入 `## 条目区` 末尾(文件内升序,继续现有编号),**禁止文件尾追加与乱序插入**。
39
+ - **Do NOT archive LESSONS.md** — it is a project-level permanent file that accumulates across changes.
40
+
41
+ 4. **Check existing lessons for superseded/deprecated**: Scan existing active lessons in `.specs/LESSONS.md`. If this change's lessons or outcomes supersede or deprecate existing entries, update their status accordingly.
42
+
43
+ 5. **Compile the leftover issues list (problem-handling principle)**: Before the move, collect everything that remains open or known-limited in this change:
44
+ - REVIEW.md findings marked `[转待办]` (deferred — recorded but not fixed) plus any known limitations captured during the change.
45
+ - Write `.specs/<change-id>/KNOWN-ISSUES.md` — each entry: issue description, why it was deferred, and where it may surface again.
46
+ - The file moves with the change into `.specs/archive/<YYYY-MM-DD>-<change-id>/` (archived alongside the other artifacts), so the leftover issues never silently vanish after archive.
47
+ - If there are no leftovers, still state that explicitly in the file (e.g. "无遗留问题" / "No known leftover issues").
48
+
49
+ 6. **Move change to archive**: After user confirmation:
50
+ - Move `.specs/<change-id>/` to `.specs/archive/<YYYY-MM-DD>-<change-id>/`.
51
+ - Date format: YYYY-MM-DD of the archive date.
52
+ - Verify the move completed successfully (source no longer exists, destination has all files).
53
+ - **git 索引同步**:移动含 `.skill-loads/` 等隐藏目录时,用 `git mv` 逐项移动或移动后用 `git add -A .specs/` 同步索引——文件系统 `mv` 后 git 索引不同步,`git checkout` 会从树恢复残留文件(实测:归档后 checkout 恢复 9 个 .skill-loads 源路径文件)。
54
+
55
+ 7. **Update CHANGELOG.md**: 在 `.specs/CHANGELOG.md` **顶部**按日期倒序插入新条目(倒序约定:新条目永远在最新日期行之上;文件不存在则从模板创建)。若项目既有 CHANGELOG 采用其他格式(如 `## 日期 + 列表`),**跟随项目既有格式**在顶部插入(不强制转表格——保持仓库一致性;guard 的倒序检测只针对表格格式行):
56
+ - 表格格式: `| YYYY-MM-DD | <change-id> | one-line summary | PR link | new L-NNN entries |`
57
+
58
+ 8. **Update STATE.md(可选决策日志)**: 若项目维护 `STATE.md`,新决策日志条目**顶部**插入(倒序约定,**禁止文件尾追加**)。flow-comet 的活动 change 状态由 `.flow-comet/flow-comet-state.json` 管理——STATE.md 无 active change 字段,不需要也不应手动清除。
59
+
60
+ 9. **Notify user of architecture sedimentation + leftover issues**: Check DESIGN.md section 9 for sedimentation suggestions. If N > 0 suggestions exist, tell user — and always explicitly enumerate the leftover issues from KNOWN-ISSUES.md in the archive notification (they must not silently disappear after archive):
61
+ ```
62
+ Archived to .specs/archive/<YYYY-MM-DD>-<change-id>/
63
+ 遗留问题清单(KNOWN-ISSUES.md,随工件归档): <each leftover issue, or 无>
64
+ This change's DESIGN section 9 has N architecture sedimentation candidates, deferred for batch sync.
65
+ Recommended: run A-evolve workflow after >= 5 changes or 60 days to batch-review and patch CONTEXT.md.
66
+ ```
67
+
68
+ 10. **Record evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` to record archive completion.
69
+
70
+ 11. **Exit check**: Run exit check.
71
+
72
+ ### 归档提交(R4.1 交付闭环)
73
+
74
+ 1. 用显式路径 stage:只 stage 本 change 可归属路径(原活动路径、实际归档路径、改过的主 spec)
75
+ 2. `git diff --cached --stat` 检查后,单一 commit:`chore: archive <change-id>`
76
+ 3. 按用户确认的交付方式 push / 建 PR(如用 git 流水线)
77
+ 4. 归档操作(移动文件)必须用户确认后才执行(不可逆)
78
+
79
+ ### 分支收尾(branchMode=true 时)
80
+
81
+ 分支模式下(`branchMode=true`,git 仓库 + init 已建 `change/<id>` 分支)在完成上述归档提交后执行收尾:
82
+
83
+ 1. 确认当前分支 = `change/<id>`(`git branch --show-current`;entry archive 已校验,异常先切回)
84
+ 2. `git checkout <默认分支> && git merge change/<id>`——冲突时**提示用户处理,禁止自动解决冲突**。默认分支不一定是 `main`(如 e2e 项目是 `master`)——先探测:`git symbolic-ref refs/remotes/origin/HEAD`(取 `origin/xxx` 的 xxx;无远端时 `git symbolic-ref --short HEAD` 的默认分支或 `git branch` 列第一个非 change 分支)
85
+ 3. `git branch -d change/<id>` 删除已合并分支
86
+ 4. `.specs/archive/` 归档照旧——分支合并是收尾动作,不是新节点
87
+
88
+ **`enablePrReview=true` 时**(用户已开启 PR 审查):**先推送分支 + 创建 PR,PR approve 后再走合并**——
89
+
90
+ 1. `git push -u origin change/<id>` 推送分支
91
+ 2. 创建 PR:`gh pr create` 或提示用户手动在 GitHub 创建
92
+ 3. PR approve 后回到第 2 步的合并流程(`git checkout <默认分支> && git merge change/<id>`——默认分支按第 2 步探测逻辑,不假设 `main`)
93
+
94
+ The full archive protocol and templates are in:
95
+ - `flow-kit/prompts/7-integration.md` (INTEGRATION phase, archive + LESSONS sections)
96
+
97
+ ### Completion reasoning
98
+
99
+ This node is truly done when:
100
+ - `.specs/<change-id>/` has been moved to `.specs/archive/<YYYY-MM-DD>-<change-id>/`.
101
+ - `.specs/CHANGELOG.md` has been updated with the change entry.
102
+ - `.specs/LESSONS.md` has been updated with any qualifying new lessons.
103
+ - `.specs/archive/<YYYY-MM-DD>-<change-id>/KNOWN-ISSUES.md` exists (leftover issues compiled and archived; explicit "无遗留" when none).
104
+ - The archive notification explicitly enumerated the leftover issues list.
105
+ - STATE.md decision log has been updated (if the project keeps one; active change state lives in the state machine).
106
+ - User has confirmed the archive operation.
107
+ - LESSONS.md has NOT been moved or archived (it remains project-level).
108
+
109
+ ### Red flags
110
+
111
+ - **Agent thought**: "Archive is just moving files, no need to ask." **Actual risk**: Archiving without user confirmation is irreversible — if the user wanted to add something or the change is not actually complete, the archive operation cannot be undone. Always ask first.
112
+ - **Agent thought**: "LESSONS.md is part of the change, archive it too." **Actual risk**: Archiving LESSONS.md with the change removes project-level knowledge that should persist across changes. LESSONS.md is permanent and must stay in `.specs/`.
113
+ - **Agent thought**: "No lessons to nominate, skip the scan." **Actual risk**: Even if no lessons qualify, the scan must be performed and documented. Skipping means potentially valuable knowledge is lost.
114
+ - **Agent thought**: "Update CONTEXT.md with DESIGN section 9 suggestions during archive." **Actual risk**: Directly updating CONTEXT.md during archive violates the A-evolve workflow. Section 9 suggestions are deferred for batch sync, not applied immediately.
115
+ - **Agent thought**: "Archived, done — the leftover issues will sort themselves out." **Actual risk**: Deferred findings and known limitations that are not compiled into KNOWN-ISSUES.md silently vanish after the archive move. Compile the leftover list before moving and enumerate it in the archive notification.
116
+
117
+ ## Entry Check
118
+
119
+ ```bash
120
+ node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry archive
121
+ ```
122
+
123
+ ## Skill Implementation
124
+
125
+ Load `flow-comet-archive` for this Node. Operation: `require`.
126
+
127
+ The archive node scans all SUMMARY.md files for lessons (applying more than 30 minutes of debugging / cross-task applicability / 6-month retry criteria), adds qualifying lessons to `.specs/LESSONS.md`, moves the change directory to `.specs/archive/`, and updates `.specs/CHANGELOG.md`. It requires user confirmation before the irreversible file move.
128
+
129
+ ## Required Skill Calls
130
+
131
+ | Skill | Enforcement | Reason |
132
+ |-------|-------------|--------|
133
+ | `flow-comet-integration` | Required for LESSONS nomination protocol | Provides nomination criteria and LESSONS.md format |
134
+
135
+ Load `flow-comet-integration` during this Node and record completed check `required-skill:archive.flow-comet-integration`. Reason: 归档 + LESSONS
136
+
137
+ **加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
138
+
139
+ 1. **用 Skill 工具加载** `flow-comet-integration`(本节点 Required Skill Call)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让 flow-comet-integration 指令生效的是 Skill 工具把它注入本次会话。
140
+ 2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
141
+
142
+ ```bash
143
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load archive flow-comet-integration --prompt flow-kit/prompts/7-integration.md
144
+ ```
145
+
146
+ > **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做。
147
+
148
+ ## Augmentations
149
+
150
+ This Node has no declared augmentations.
151
+
152
+ ## Output Schemas
153
+
154
+ Schema: `flowkit.archive.v1`
155
+
156
+ | Schema ID | Artifact Kind | Required | Path |
157
+ |-----------|--------------|----------|------|
158
+ | `archive-dir` | directory | yes | `.specs/archive/<YYYY-MM-DD>-<change-id>/` |
159
+ | `known-issues` | file | required | `.specs/archive/<YYYY-MM-DD>-<change-id>/KNOWN-ISSUES.md` (leftover issues list, archived with the change; 无遗留也显式写「无遗留问题」——guard 强制存在) |
160
+ | `changelog-entry` | file | yes | `.specs/CHANGELOG.md` (inserted at the top, reverse-chronological) |
161
+ | `lessons-updated` | file | conditional | `.specs/LESSONS.md` (if new lessons nominated) |
162
+
163
+ Evidence: `archive-summary` (required)
164
+
165
+ ## Evidence Record
166
+
167
+ ```bash
168
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summary":"Change archived to .specs/archive/<date>-<id>/, N lessons added, CHANGELOG updated"}'
169
+ ```
170
+
171
+ ## Guardrails
172
+
173
+ | Guardrail ID | Label | Validation Type |
174
+ |--------------|-------|-----------------|
175
+ | `archive-evidence` | Archive directory exists, source removed | state-transition |
176
+ | `changelog-updated` | CHANGELOG.md has new entry | 执行纪律(review 把关),guard 不校验(倒序位置有 WARN 渐进检查) |
177
+ | `lessons-preserved` | LESSONS.md still in .specs/ (not archived) | 执行纪律(review 把关),guard 不校验 |
178
+ | `user-confirmed` | User confirmed archive before execution | 执行纪律(review 把关),guard 不校验 |
179
+
180
+ ## Exit Check
181
+
182
+ ```bash
183
+ node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit archive --apply
184
+ ```
185
+
186
+ If the script prints `NEXT: done`, summarize the workflow evidence and stop. The change is complete.
187
+
188
+ ## Recovery
189
+
190
+ 1. Re-run entry check to confirm workflow state.
191
+ 2. Check if `.specs/<change-id>/` still exists (not yet archived) or if `.specs/archive/<YYYY-MM-DD>-<change-id>/` exists (already archived).
192
+ 3. If not yet archived: resume from the first incomplete step (lessons scan, archive move, CHANGELOG update).
193
+ 4. If already archived but CHANGELOG not updated: update CHANGELOG.md manually.
194
+ 5. If already archived but LESSONS not updated: scan SUMMARY.md files in the archive directory and update LESSONS.md.
195
+ 6. If partially archived (source removed but destination incomplete): investigate and complete the move.
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: flow-comet-change
3
+ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生成、架构级变更检测、视觉调性预选。flow-comet open 节点的 flow-kit 增强。"
4
+ ---
5
+
6
+ # flow-kit CHANGE Protocol
7
+
8
+ 本 Skill 为 flow-comet 的 open 节点提供 flow-kit 的 CHANGE 反问协议。
9
+
10
+ ## 加载
11
+
12
+ 读取 `flow-kit/prompts/0-change.md` 并按其执行。关键步骤:
13
+
14
+ 1. **自动生成 change-id**(kebab-case,2~4 词,检查 `.specs/<id>/` 不冲突)
15
+ 2. **架构级变更检测**(步骤 0.4):命中 5 类信号时暂停,引导先跑 A-architect
16
+ 3. **前端项目识别**(步骤 0.5):关键词判定是否为前端项目
17
+ 4. **视觉调性预选**(步骤 0.6,仅前端):9 张调性卡片 + 推荐
18
+ 5. **结构化反问**(步骤 1):每轮最多 3 个问题
19
+ 6. **影响面判定 + 范围排除**
20
+ 7. **生成 CHANGE.md**(使用 `flow-kit/templates/CHANGE.md`)
21
+ 8. **路径建议**:完整/中等/最短
22
+
23
+ ## 产物
24
+
25
+ - `.specs/<change-id>/CHANGE.md`
26
+
27
+ ## 状态推进
28
+
29
+ CHANGE.md 生成后,由 flow-comet 状态机(workflow-state/guard)推进节点。不需要手动维护 STATE.md。
@@ -0,0 +1,249 @@
1
+ ---
2
+ name: flow-comet-compose
3
+ description: "Use only when explicitly invoked as /flow-comet-compose. Not part of the 8-node flow. Guides composing installed skills into a custom workflow protocol JSON, driven by the flow-comet kernel (state routing / guard validation / hook interception)."
4
+ ---
5
+
6
+ # flow-comet-compose(横向命令 · 自定义协议组装)
7
+
8
+ ## 定位
9
+
10
+ `flow-comet-compose` 是横向命令(与 flow-comet-evolve / flow-comet-health 同类),**独立 skill,不是 8 节点流程的一部分**。它引导用户把任意已安装 skill 组合成自定义工作流,并生成 workflow-kernel 协议 JSON(protocol)。
11
+
12
+ 自定义协议生成后,由 flow-comet 现有机制完整驱动,无需新增任何运行时能力:
13
+
14
+ - **状态机路由**:`workflow-state.mjs` 按节点顺序推进、记录 evidence、管理状态
15
+ - **guard 校验**:`workflow-guard.mjs` 按节点 guardrail(artifact-exists / evidence-only / state-transition)做阶段门禁
16
+ - **hook 拦截**:`comet-hook-guard.mjs` 按 writeWhitelist 做写入边界守卫
17
+
18
+ **内置 8 节点协议不可被取代**:`reference/workflow-protocol.json`(open→design→plan→execute→subagent-execute→review→verify→archive)永远是默认工作流;自定义协议只在用户显式指定时加载(见「与内置协议的关系」)。
19
+
20
+ ## 交互流程(逐步)
21
+
22
+ ### Step 1:目标收集
23
+
24
+ 问用户「做什么 + 要哪些机制」。**每轮最多 3 问,答完一轮再问下一轮**,禁止一次性倾倒全部问题:
25
+
26
+ 1. 你要组合的流程解决什么问题?期望的节点序列是什么?
27
+ 2. 需要哪些机制?(状态机路由 / guard 产物校验 / hook 写入拦截 / handoff 子代理交接)
28
+ 3. 每个节点输出什么产物、记录什么 evidence?
29
+
30
+ 用户回答不完整时,只追问缺口,不复述已确认内容。
31
+
32
+ ### Step 2:skill 库扫描
33
+
34
+ 1. 列出已安装 skill:`ls .claude/skills/` 与 `ls .flow-comet/skills/`;用户也可直接提供候选 skill 名。
35
+ 2. 把候选列表贴给用户,确认组合:哪些 skill 作为节点 implementation,哪些作为 requiredSkillCalls。
36
+ 3. 确认每个 skill 实际存在;不存在时标记为占位并提醒用户安装。
37
+
38
+ ### Step 3:节点组装
39
+
40
+ 用户确定节点序列后,为**每个节点**绑定:
41
+
42
+ | 字段 | 说明 |
43
+ |------|------|
44
+ | `id` | 节点唯一标识(英文,避免与内置 8 节点 id 冲突,见强制最小规则 3) |
45
+ | `label` | 展示名 |
46
+ | `kind` | `control` / `handoff` |
47
+ | `responsibility` | 该节点职责(一句话) |
48
+ | `implementation.skill` | 节点执行 skill(`require` / `augment` / `override`) |
49
+ | `requiredSkillCalls` | 必调 skill 列表(可空) |
50
+ | `outputSchemas` | 引用的产物 schema id(必须与顶层 `outputSchemas[]` 对应) |
51
+ | `guardrails` | 可选:阶段门禁(artifact-exists / evidence-only / state-transition) |
52
+
53
+ ### Step 4:协议生成
54
+
55
+ 按 workflow-kernel schema 写 JSON(锚点见 `../flow-comet/reference/workflow-protocol.json`):
56
+
57
+ - 必填顶层字段:`schemaVersion: 1`、`kind: "workflow-kernel"`、`name`、`goal`、`nodes[]`、`outputSchemas[]`、`state{}`
58
+ - **`edges` 可省略 = 顺序推进**:不写 edges 时按 `nodes[]` 数组顺序推进,同内置协议行为;写 edges 则按显式转移表路由
59
+ - 可选顶层字段:
60
+ - `writeWhitelist`:hook 白名单(节点 id → 允许写入的路径前缀数组)。**路径支持 `<change-id>` 占位符**(与 outputSchemas 的 artifacts paths 同机制,协议复用自动适配当前 change)。**未声明时**:内置节点 id 用内置白名单表;**自定义节点 id 默认协调者白名单 `['.specs/']`**(写源码必须显式声明)
61
+ - `taskFile`:任务文件路径字符串
62
+
63
+ 生成的协议**写用户指定路径**(建议 `.specs/` 或项目根,例如 `.specs/protocols/<name>.json`),并在写前与用户确认。
64
+
65
+ ### Step 5:冒烟验证
66
+
67
+ **生成的协议必须通过 `validateProtocolSchema`**(fail-closed:schemaVersion 必须为 1、nodes 必须是非空数组、writeWhitelist/taskFile 存在则校验形状)。校验命令(把 `<协议路径>` 换成实际路径):
68
+
69
+ ```bash
70
+ node --input-type=module -e "
71
+ import { readFileSync } from 'node:fs';
72
+ import { validateProtocolSchema } from './.claude/skills/flow-comet/scripts/protocol-utils.mjs';
73
+ const protocol = JSON.parse(readFileSync('<协议路径>', 'utf8'));
74
+ validateProtocolSchema(protocol);
75
+ console.log('protocol valid');
76
+ "
77
+ ```
78
+
79
+ - `protocol-utils.mjs` 位于 flow-comet skill 的 `scripts/` 目录;若 bundle 未安装为 `.claude/skills/flow-comet`,按实际路径(如 `.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs`)调整
80
+ - 校验不通过 → 修复字段 → 重跑,直到输出 `protocol valid`
81
+ - 校验通过后,把校验命令与输出写入该协议所在目录的验证记录(或直接回显给用户),作为协议生效证据
82
+
83
+ ## 强制最小规则(质量语义,不可跳过)
84
+
85
+ 1. **每节点必须有产物**:节点 `outputSchemas` 引用的 schema 必须存在于顶层 `outputSchemas[]`,且含非空 `artifacts[].paths`。禁止无产物节点——没有产物就无法做 guard 校验与恢复。
86
+ 2. **每节点必须有 evidence 字段**:每个 outputSchema 必须带 `evidence: [{ id, required }]`(flowkit.*.v1 风格),供 `workflow-state.mjs record` 记录节点证据。
87
+ 3. **节点 id 避免与内置 8 节点 id 冲突**:`open` / `design` / `plan` / `execute` / `subagent-execute` / `review` / `verify` / `archive` 为内置保留 id,自定义协议不得复用——防止特化校验(ADR-002 语义)误触发。
88
+ 4. **协议路径由用户指定**:生成的协议写用户指定路径(建议 `.specs/` 或项目根),禁止擅自写入 bundle 或 skill 目录。
89
+
90
+ ## 产物示例(最小 3 节点协议)
91
+
92
+ 以下示例组合「头脑风暴 → TDD 实现 → 代码审查」三个节点,节点 id 用 `brainstorm` / `tdd` / `codereview`(第三个节点的 id 避开内置 `review`,标签仍为 Review——见强制最小规则 3),`implementation.skill` 为占位 skill 名(使用前替换为实际已安装 skill),`outputSchemas` 引用自定义 schema(`compose.*.v1`)。edges 省略 = 顺序推进。
93
+
94
+ ```json
95
+ {
96
+ "schemaVersion": 1,
97
+ "kind": "workflow-kernel",
98
+ "name": "brainstorm-tdd-review",
99
+ "goal": "示例:头脑风暴 → TDD 实现 → 代码审查 的轻量自定义流程",
100
+ "nodes": [
101
+ {
102
+ "id": "brainstorm",
103
+ "label": "Brainstorm",
104
+ "kind": "control",
105
+ "responsibility": "澄清意图与需求,产出 BRAINSTORM.md",
106
+ "implementation": {
107
+ "skill": "superpowers:brainstorming",
108
+ "operation": "require",
109
+ "scope": "main",
110
+ "enforcement": "guarded"
111
+ },
112
+ "operations": ["require", "augment"],
113
+ "requiredSkillCalls": [],
114
+ "outputSchemas": ["compose.brainstorm.v1"],
115
+ "guardrails": [
116
+ {
117
+ "id": "brainstorm-artifacts",
118
+ "label": "BRAINSTORM.md exists",
119
+ "validation": "artifact-exists"
120
+ }
121
+ ],
122
+ "augmentations": [],
123
+ "satisfies": [],
124
+ "disabled": false
125
+ },
126
+ {
127
+ "id": "tdd",
128
+ "label": "TDD",
129
+ "kind": "control",
130
+ "responsibility": "按 TDD 实现功能,产出 SUMMARY.md",
131
+ "implementation": {
132
+ "skill": "superpowers:test-driven-development",
133
+ "operation": "require",
134
+ "scope": "main",
135
+ "enforcement": "guarded"
136
+ },
137
+ "operations": ["require", "augment"],
138
+ "requiredSkillCalls": [],
139
+ "outputSchemas": ["compose.tdd.v1"],
140
+ "guardrails": [
141
+ {
142
+ "id": "tdd-evidence",
143
+ "label": "SUMMARY.md produced",
144
+ "validation": "artifact-exists"
145
+ }
146
+ ],
147
+ "augmentations": [],
148
+ "satisfies": [],
149
+ "disabled": false
150
+ },
151
+ {
152
+ "id": "codereview",
153
+ "label": "Review",
154
+ "kind": "control",
155
+ "responsibility": "代码审查,产出 REVIEW.md",
156
+ "implementation": {
157
+ "skill": "superpowers:requesting-code-review",
158
+ "operation": "require",
159
+ "scope": "main",
160
+ "enforcement": "guarded"
161
+ },
162
+ "operations": ["require", "augment"],
163
+ "requiredSkillCalls": [],
164
+ "outputSchemas": ["compose.review.v1"],
165
+ "guardrails": [
166
+ {
167
+ "id": "review-artifacts",
168
+ "label": "REVIEW.md exists",
169
+ "validation": "artifact-exists"
170
+ }
171
+ ],
172
+ "augmentations": [],
173
+ "satisfies": [],
174
+ "disabled": false
175
+ }
176
+ ],
177
+ "outputSchemas": [
178
+ {
179
+ "id": "compose.brainstorm.v1",
180
+ "description": "BRAINSTORM.md",
181
+ "artifacts": [
182
+ {
183
+ "id": "brainstorm-doc",
184
+ "kind": "file",
185
+ "required": true,
186
+ "paths": ["<change-id>/BRAINSTORM.md"],
187
+ "pathBase": "specs-root"
188
+ }
189
+ ],
190
+ "evidence": [
191
+ { "id": "brainstorm-summary", "required": true }
192
+ ]
193
+ },
194
+ {
195
+ "id": "compose.tdd.v1",
196
+ "description": "SUMMARY.md per task",
197
+ "artifacts": [
198
+ {
199
+ "id": "task-summaries",
200
+ "kind": "file",
201
+ "required": true,
202
+ "paths": ["<change-id>/*-SUMMARY.md"],
203
+ "pathBase": "specs-root"
204
+ }
205
+ ],
206
+ "evidence": [
207
+ { "id": "implementation-summary", "required": true }
208
+ ]
209
+ },
210
+ {
211
+ "id": "compose.review.v1",
212
+ "description": "REVIEW.md",
213
+ "artifacts": [
214
+ {
215
+ "id": "review-doc",
216
+ "kind": "file",
217
+ "required": true,
218
+ "paths": ["<change-id>/REVIEW.md"],
219
+ "pathBase": "specs-root"
220
+ }
221
+ ],
222
+ "evidence": [
223
+ { "id": "review-summary", "required": true }
224
+ ]
225
+ }
226
+ ],
227
+ "state": {
228
+ "kind": "workflow-run",
229
+ "statePath": ".flow-comet/flow-comet-state.json",
230
+ "currentNodeField": "currentNode",
231
+ "completedNodesField": "completedNodes",
232
+ "evidenceField": "evidence"
233
+ }
234
+ }
235
+ ```
236
+
237
+ ## 与内置协议的关系
238
+
239
+ | 维度 | 内置 8 节点协议(默认) | 自定义协议 |
240
+ |------|------------------------|-----------|
241
+ | 位置 | `../flow-comet/reference/workflow-protocol.json` | 用户指定路径(建议 `.specs/` 或项目根) |
242
+ | 加载时机 | 未显式指定时一律使用 | 用户显式指定 `--protocol` 或 `FLOW_COMET_PROTOCOL` |
243
+ | 优先级 | 最低(默认) | `--protocol` CLI 参数 > `FLOW_COMET_PROTOCOL` 环境变量 > 内置默认(resolveProtocol) |
244
+ | 驱动机制 | workflow-state.mjs + workflow-guard.mjs + comet-hook-guard.mjs | 同一套机制,零差异 |
245
+
246
+ - **加载方式**:`--protocol <path>`(或 `--protocol=<path>`)CLI 参数,或 `FLOW_COMET_PROTOCOL` 环境变量;两种方式均被工作流脚本(resolveProtocol)支持。
247
+ - **hook 白名单**:自定义协议可声明 `writeWhitelist`(节点 id → 路径前缀数组,**支持 `<change-id>` 占位符**);缺省时内置节点 id 用内置白名单表、**自定义节点 id 用协调者默认 `['.specs/']`**(写源码必须显式声明——防 fail-open)。
248
+ - **默认不可变**:自定义协议不持久化生效,未显式指定时一切行为与内置协议完全一致;内置 8 节点协议始终可用,作为默认工作流不可被取代。
249
+ - 自定义协议与内置协议互不干扰,可并存;切换只需修改启动参数或环境变量。
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: flow-comet-design
3
+ description: "Use only when explicitly invoked as /flow-comet-design or routed by the flow-comet entry/runtime to the design Node; complete Design for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
4
+ ---
5
+
6
+ # Design
7
+
8
+ ## Node Goal
9
+
10
+ Complete the `design` Node for `flow-comet`.
11
+
12
+ Responsibility: 技术栈选型 + ADR + 数据流。生成 DESIGN.md。
13
+
14
+ ## Guidance
15
+
16
+ ### 必填段清单(结构+存在级)
17
+
18
+ | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
19
+ |------|-------------------------------|-----------------------------------|
20
+ | DESIGN.md | `## 0.` 技术栈段 / `## 1. 决策清单` | `## 0.5 架构对齐` / `## 风险` / `## 数据流` 等 |
21
+
22
+ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / templateSectionPatterns;「填得好不好」由 review 把关。
23
+