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.
- package/.flow-comet/rules/flow-comet-orchestration.md +13 -0
- package/.flow-comet/skills/flow-comet/GUIDANCE.md +196 -0
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -0
- package/.flow-comet/skills/flow-comet/SKILL.md +196 -0
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +19 -0
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +115 -0
- package/.flow-comet/skills/flow-comet/reference/authoring-lanes.json +33 -0
- package/.flow-comet/skills/flow-comet/reference/composition-report.md +65 -0
- package/.flow-comet/skills/flow-comet/reference/decision-points.md +64 -0
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +30 -0
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +169 -0
- package/.flow-comet/skills/flow-comet/reference/init-detection.md +58 -0
- package/.flow-comet/skills/flow-comet/reference/recovery.md +20 -0
- package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +661 -0
- package/.flow-comet/skills/flow-comet/reference/skill-review.md +13 -0
- package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +7 -0
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +681 -0
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +52 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +61 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +909 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-plan.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +312 -0
- package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +136 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +7331 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +376 -0
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +230 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +99 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +4017 -0
- package/.flow-comet/skills/flow-comet/scripts/task-parsing.mjs +28 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +2396 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +378 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +1263 -0
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +195 -0
- package/.flow-comet/skills/flow-comet-change/SKILL.md +29 -0
- package/.flow-comet/skills/flow-comet-compose/SKILL.md +249 -0
- package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +23 -0
- package/.flow-comet/skills/flow-comet-design/SKILL.md +161 -0
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +51 -0
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +26 -0
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +182 -0
- package/.flow-comet/skills/flow-comet-health/SKILL.md +31 -0
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +45 -0
- package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +36 -0
- package/.flow-comet/skills/flow-comet-open/SKILL.md +161 -0
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +33 -0
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +169 -0
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +27 -0
- package/.flow-comet/skills/flow-comet-review/SKILL.md +204 -0
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +29 -0
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +214 -0
- package/.flow-comet/skills/flow-comet-task/SKILL.md +33 -0
- package/.flow-comet/skills/flow-comet-test/SKILL.md +41 -0
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +26 -0
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +164 -0
- package/LICENSE +21 -0
- package/README.md +255 -0
- package/package.json +27 -0
- package/scripts/dsh-bridge.mjs +461 -0
- package/scripts/prepare-env.mjs +1526 -0
|
@@ -0,0 +1,161 @@
|
|
|
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
|
+
<!-- 手写区详细协议见 GUIDANCE.md(可选阅读) -->
|
|
7
|
+
|
|
8
|
+
# Design
|
|
9
|
+
|
|
10
|
+
## Node Goal
|
|
11
|
+
|
|
12
|
+
Complete the `design` Node for `flow-comet`.
|
|
13
|
+
|
|
14
|
+
Responsibility: 技术栈选型 + ADR + 数据流。生成 DESIGN.md(轻量流程为 DESIGN-lite.md)。
|
|
15
|
+
|
|
16
|
+
## Guidance
|
|
17
|
+
|
|
18
|
+
### 必填段清单(结构+存在级)
|
|
19
|
+
|
|
20
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
21
|
+
|------|-------------------------------|-----------------------------------|
|
|
22
|
+
| DESIGN.md | `## 0.` 技术栈段 / `## 1. 决策清单` | `## 0.5 架构对齐` / `## 风险` / `## 数据流` 等 |
|
|
23
|
+
|
|
24
|
+
> **决策清单段名须与模板精确一致**:guard 按 flow-kit 模板段名派生校验——模板段为 `## 1. 决策清单`(编号可选),**不要写成"技术决策清单"等变体**(2-design.md 指引的"技术决策"是内容要求,不是段名;实测:写变体段名会被拦截)。
|
|
25
|
+
|
|
26
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / templateSectionPatterns;「填得好不好」由 review 把关。
|
|
27
|
+
|
|
28
|
+
# Design
|
|
29
|
+
|
|
30
|
+
## Node Goal
|
|
31
|
+
|
|
32
|
+
This node transforms requirements into an actionable technical design. It produces DESIGN.md with tech stack decisions, architecture alignment with existing modules, ADRs for reversible decisions, data flow diagrams, and risk assessment. For frontend projects, it additionally produces UI-DESIGN.md with design tokens and visual specifications. The output artifacts serve as the blueprint for task decomposition and implementation.
|
|
33
|
+
|
|
34
|
+
## Guidance
|
|
35
|
+
|
|
36
|
+
### Prerequisites
|
|
37
|
+
|
|
38
|
+
- `.specs/<change-id>/CHANGE.md` must exist (produced by open node).
|
|
39
|
+
- `.specs/<change-id>/REQUIREMENT.md` must exist (produced by open node).
|
|
40
|
+
- If `.specs/ARCHITECTURE.md` exists, it should be read (sections 2, 3, 4) for module boundaries, ADR conflicts, and cross-module contracts.
|
|
41
|
+
- `flow-kit/reference/tech-stacks.md` must be accessible for tech stack card selection.
|
|
42
|
+
|
|
43
|
+
### Steps
|
|
44
|
+
|
|
45
|
+
1. **Architecture change pre-check (0-)**: If CHANGE.md already has "Architecture Impact Statement" or "Post A-architect" marker, skip. Otherwise re-evaluate against the 5 criteria from `0-change.md` step 0.4.1. If hit + ARCHITECTURE.md exists: check ADR conflict. If hit + no ARCHITECTURE.md: present 3 options to user. If not hit: proceed.
|
|
46
|
+
|
|
47
|
+
2. **Tech stack preselection (section 0)**: Load `flow-kit/reference/tech-stacks.md`. Filter to 5-6 cards matching project type. Present with 1 preferred + 1 backup (reasoning from REQUIREMENT ACs + non-functional requirements). Exclude 1-2 with reasons. Wait for user selection. Exception: if CONTEXT.md has locked tech decisions, use those directly.
|
|
48
|
+
|
|
49
|
+
3. **Existing architecture alignment (section 0.5, brownfield only)**: This is the most critical step for existing projects:
|
|
50
|
+
- **0.5.1 Touched modules**: Grep (not guess) actual modules that will be touched. List: existing modules to modify, existing modules to reuse, new modules to create, forbidden modules (DO NOT TOUCH).
|
|
51
|
+
- **0.5.2 Align existing abstractions**: For each capability needed, check if existing code already provides it. Table format: "Need X | Existing Y exists | Decision: reuse" or "Need X | None exists | Decision: create (reason: first time)".
|
|
52
|
+
- **0.5.3 Reuse vs new patterns**: For each key decision, declare "reuse" (with reference) or "introduce new" (with justification). New patterns require explicit reason.
|
|
53
|
+
- **0.5.4 Write to DESIGN.md section 0.5**: All of the above goes into DESIGN.md.
|
|
54
|
+
|
|
55
|
+
4. **Technical decisions (section 1)**: Each decision must have: decision + alternatives + selection reason + trade-off cost. "Use best practice" is forbidden — must be specific.
|
|
56
|
+
|
|
57
|
+
5. **Data flow / architecture diagram (section 2)**: ASCII or Mermaid diagram showing data/event flow, key state machines, boundaries.
|
|
58
|
+
|
|
59
|
+
6. **ADR (section 3)**: For any decision that could be reversed later, write ADR to `.specs/adr/<NNN>-<title>.md` with Context / Decision / Consequences structure.
|
|
60
|
+
|
|
61
|
+
7. **Risk assessment (section 4)**: At least 3 risks (implementation / launch / long-term debt), each with mitigation.
|
|
62
|
+
|
|
63
|
+
8. **Out of scope (section 5)**: Explicitly list what this design does NOT solve but will need future attention.
|
|
64
|
+
|
|
65
|
+
9. **Architecture sedimentation suggestions (section 9)**: If this change introduces project-level reusable value (new abstractions, tech decisions, cross-module contracts, dependency changes, forbidden-list updates), fill section 9. Otherwise write "No architecture sedimentation suggestions for this change."
|
|
66
|
+
|
|
67
|
+
10. **UI-DESIGN.md (frontend only)**: If project is frontend, load `flow-comet-ui-design` skill. Produce design tokens (OKLCH colors, fonts, spacing, animation), anti-AI-slop check, visual north star.
|
|
68
|
+
|
|
69
|
+
11. **LESSONS scan**: Grep `.specs/LESSONS.md` for keywords related to touched modules or tech decisions. If active lessons hit, declare difference or confirm still applies.
|
|
70
|
+
|
|
71
|
+
The full design protocol, templates, and anti-patterns are in:
|
|
72
|
+
- `flow-kit/prompts/2-design.md` (DESIGN phase)
|
|
73
|
+
- `flow-kit/prompts/2a-ui-design.md` (UI-DESIGN phase, frontend only)
|
|
74
|
+
|
|
75
|
+
### Completion reasoning
|
|
76
|
+
|
|
77
|
+
This node is truly done when:
|
|
78
|
+
- `.specs/<change-id>/DESIGN.md` — 或轻量流程的 `.specs/<change-id>/DESIGN-lite.md` — exists with section 0 (tech stack selected) populated.
|
|
79
|
+
- Section 0.5 (existing architecture alignment) is populated for brownfield projects.
|
|
80
|
+
- Each technical decision has alternatives + reason + trade-off.
|
|
81
|
+
- At least 1 data flow / architecture diagram exists.
|
|
82
|
+
- Risk section has at least 3 items with mitigations.
|
|
83
|
+
- User has confirmed tech stack and key decisions.
|
|
84
|
+
- For frontend: `.specs/<change-id>/UI-DESIGN.md` exists with design tokens.
|
|
85
|
+
|
|
86
|
+
### Red flags
|
|
87
|
+
|
|
88
|
+
- **Agent thought**: "Tech stack is obvious from the project, no need to ask." **Actual risk**: Choosing tech stack without user confirmation violates the interactive protocol. Always present cards and wait.
|
|
89
|
+
- **Agent thought**: "I know the module boundaries from memory." **Actual risk**: Not grepping actual module boundaries leads to DESIGN.md section 0.5 referencing non-existent paths or missing real touched modules. Must grep, not guess.
|
|
90
|
+
- **Agent thought**: "Section 0.5 is optional for small changes." **Actual risk**: Even small changes on brownfield projects can accidentally touch forbidden modules. Section 0.5 is mandatory when CONTEXT.md exists.
|
|
91
|
+
- **Agent thought**: "ADR is only for big decisions." **Actual risk**: Any decision that could be reversed later needs an ADR. Missing ADRs mean future changes cannot trace why the current approach was chosen.
|
|
92
|
+
- **Agent thought**: "DESIGN.md can include full code implementations." **Actual risk**: Violates R3.1 (Architect does not write implementation code). Pseudocode and function signatures are OK; full function bodies are not.
|
|
93
|
+
|
|
94
|
+
## Entry Check
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry design
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Skill Implementation
|
|
101
|
+
|
|
102
|
+
The design node reads CHANGE.md and REQUIREMENT.md, then produces DESIGN.md through interactive tech stack selection, architecture alignment (grepping actual modules), technical decisions with ADRs, and risk assessment. For frontend projects, it additionally loads `flow-comet-ui-design` to produce UI-DESIGN.md with design tokens and visual specifications.
|
|
103
|
+
|
|
104
|
+
## Required Skill Calls
|
|
105
|
+
|
|
106
|
+
| Skill | Enforcement | Reason |
|
|
107
|
+
|-------|-------------|--------|
|
|
108
|
+
| `flow-comet-ui-design` | Advisory(仅前端项目触发) | Produces UI-DESIGN.md with design tokens, anti-AI-slop check, visual north star——advisory 条目不要求 skill-load 声明(record D3 只校验执行者实际声明的 guarded 条目) |
|
|
109
|
+
|
|
110
|
+
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
111
|
+
|
|
112
|
+
1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-design`)无需重复加载,仅需运行下方声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-ui-design` 为 advisory 条目——仅前端项目用 Skill 工具加载其已装副本,非前端项目不加载不声明;若前端项目把 `required-skill:design.flow-comet-ui-design` 记入 completedChecks,也必须先运行对应 skill-load 声明(D3 校验声明过的条目)。
|
|
113
|
+
2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-design --prompt flow-kit/prompts/2-design.md
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
120
|
+
|
|
121
|
+
## Output Schemas
|
|
122
|
+
|
|
123
|
+
Schema: `flowkit.design.v1`
|
|
124
|
+
|
|
125
|
+
| Schema ID | Artifact Kind | Required | Path |
|
|
126
|
+
|-----------|--------------|----------|------|
|
|
127
|
+
| `design-doc` | file | yes | `.specs/<change-id>/DESIGN.md` or `.specs/<change-id>/DESIGN-lite.md` |
|
|
128
|
+
| `ui-design-doc` | file | yes (frontend) | `.specs/<change-id>/UI-DESIGN.md` |
|
|
129
|
+
| `adr-docs` | file | no | `.specs/adr/<NNN>-<title>.md` (0-N files) |
|
|
130
|
+
|
|
131
|
+
Evidence: `design-summary` (required)
|
|
132
|
+
|
|
133
|
+
## Evidence Record
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record design '{"summary":"DESIGN.md produced with tech stack, architecture alignment, ADRs, risks"}'
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Guardrails
|
|
140
|
+
|
|
141
|
+
| Guardrail ID | Label | Validation Type |
|
|
142
|
+
|--------------|-------|-----------------|
|
|
143
|
+
| `design-artifacts` | DESIGN.md (or DESIGN-lite.md) exists with section 0 | artifact-exists |
|
|
144
|
+
| `architecture-aligned` | Section 0.5 populated for brownfield | 执行纪律(review 把关),guard 不校验 |
|
|
145
|
+
| `ui-design-artifacts` | UI-DESIGN.md exists for frontend projects | 执行纪律(review 把关),guard 不校验 |
|
|
146
|
+
|
|
147
|
+
## Exit Check
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit design --apply
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
If the script prints `SKILL: flow-comet-plan`, load that Skill next.
|
|
154
|
+
|
|
155
|
+
## Recovery
|
|
156
|
+
|
|
157
|
+
1. Re-run entry check to confirm workflow state.
|
|
158
|
+
2. Read `.specs/<change-id>/DESIGN.md` — 轻量流程允许 `.specs/<change-id>/DESIGN-lite.md`(guard 同口径:DESIGN.md 优先、DESIGN-lite 兜底)——if exists with section 0 populated and user confirmed, design phase is done.
|
|
159
|
+
3. If the design doc exists but incomplete, resume from the first missing section (check 0, 0.5, 1-5, 9).
|
|
160
|
+
4. If frontend project: check `.specs/<change-id>/UI-DESIGN.md` existence.
|
|
161
|
+
5. Do not repeat confirmed decisions. Resume from the first incomplete artifact.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-dev
|
|
3
|
+
description: "flow-kit DEV 阶段协议:TDD + 6 维自查 + diff 边界 verify + LESSONS 扫描 + R4.5 Schema 迁移 + R4.6 破坏性变更。flow-comet execute/subagent-execute 节点的 flow-kit 增强。"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# flow-kit DEV Protocol
|
|
7
|
+
|
|
8
|
+
本 Skill 为 flow-comet 的 execute/subagent-execute 节点提供 flow-kit 的完整开发规则集。
|
|
9
|
+
|
|
10
|
+
## 加载
|
|
11
|
+
|
|
12
|
+
读取 `flow-kit/prompts/4-dev.md` 并按其执行。以下是核心规则摘要(完整内容以 prompt 文件为准):
|
|
13
|
+
|
|
14
|
+
### 必跑检查
|
|
15
|
+
|
|
16
|
+
1. **沿用既有抽象 grep(R6.4)**:写代码前 grep 同类抽象,找到了 import 用
|
|
17
|
+
2. **LESSONS 扫描(R1.8)**:grep `.specs/LESSONS.md`,命中 active 条目必须声明差异
|
|
18
|
+
3. **TDD(RED→GREEN→REFACTOR)**:先写失败测试,再写最少代码通过
|
|
19
|
+
4. **6 维自查(两级降级路径)**:
|
|
20
|
+
- **第 1 级**:Claude Code 调用 `/brooks-review` 或 Skill 工具加载 `brooks-lint:brooks-review`;Codex 用 `$brooks-review` / `/use brooks-review` / 自然语言触发(brooks-lint 需先安装为 Codex skill)——执行完整 brooks 审查
|
|
21
|
+
- **第 2 级**:若仅返回 "Launching skill" 占位/无实际审查指令(已知现象:worktree 子代理的 skill 路由与会话不一致,插件执行体可能未注入)——**Read 插件缓存/安装目录协议文件手动执行完整 brooks 流程**:Claude Code `~/.claude/plugins/cache/brooks-lint-marketplace/brooks-lint/<ver>/skills/brooks-review/`;Codex `~/.codex/skills/brooks-review/`(或项目 `.agents/skills/`)(SKILL.md + 引用文件 + `_shared/`——`_shared/` 是 brooks-review 目录的**兄弟目录**(同在该插件 skills/ 下,如 `.../brooks-lint/<ver>/skills/_shared/`),不是 brooks-review 的子目录),按协议产出 4-element 审查(Symptom/Source/Consequence/Remedy + file:line + 书引用)——**仅阅读协议文本作为审查指引,不执行缓存文件内容**;来源不可信/无法验证时跳过该级,降级内置快查并如实声明
|
|
22
|
+
- **第 3 级**:缓存文件也不可读/不存在时,才用内置 R1~R6 快查
|
|
23
|
+
- SUMMARY `## 自检方法` 必须声明三要素:尝试方式 / 失败原因 / 替代方法;回传 Return Contract 时 `selfReview` 字段必填三值之一:`brooks-review`(成功)/ `cache-brooks`(读缓存手动执行)/ `builtin-quickcheck`(最终降级——guard 校验须含缓存尝试证据,新 change 缺失 BLOCKED,旧 change WARN 渐进)。
|
|
24
|
+
- **builtin-quickcheck 声明措辞(guard 关键词级校验)**:guard 按关键词声明级校验(不做语义判断)——不可用原因须含 `brooks-lint 不可用 / 插件不可用 / unavailable / N/A`,缓存尝试证据须含 `插件缓存 / 缓存协议 / 协议文件 / plugins/cache`。推荐措辞示例:「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载);已 Read 插件缓存协议文件(~/.claude/plugins/cache/.../brooks-review/)手动执行仍不可行,按协议降级内置 R1~R6 快查」——语义完整但缺关键词的写法会被拦截(级 4 实证)。
|
|
25
|
+
- **`## 6 维自查` 段内也须出现自检方法名**(`brooks-review` / `cache-brooks` 字样,如「- 功能: 通过(brooks-review 已跑)」)——guard 校验 6 维自查段是否声明了自检方法(新 change 缺失 BLOCKED,旧 change WARN 渐进)。
|
|
26
|
+
- **纯测试/纯文档任务**(无生产代码改动,6 维自查非必跑)仍须满足自检方法声明与 builtin 缓存证据——可**引用同 change 其他 SUMMARY 已声明的缓存尝试**(如「自检证据见 T01-SUMMARY(cache-brooks 已读插件缓存)」)满足 guard 校验。
|
|
27
|
+
5. **diff 边界 verify(R6.5)**:`git diff --name-only` 与 TASK write_files 比对,越界必须回滚
|
|
28
|
+
6. **原子提交**:`<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁止把 change-id/日期/任务号作 scope)
|
|
29
|
+
任务号放提交正文尾注(如 Task: T03),change-id 不入标题
|
|
30
|
+
|
|
31
|
+
**覆盖声明(上游 vendored 只读)**:vendored 上游提示文件(`flow-kit/prompts/**`、`flow-kit/templates/**`)保持只读基准,不作修改——上游(如 `flow-kit/prompts/4-dev.md` 等)旧示例以 change-id 作 scope 的写法**不采用**;本仓采用通用子系统 scope 语义(推荐可选),提交格式与本仓约束以本节为准;已登记向上游提改进待办(REQUIREMENT v2),收口前由本声明压制差异。
|
|
32
|
+
|
|
33
|
+
### 条件检查
|
|
34
|
+
|
|
35
|
+
7. **Schema 迁移协议(R4.5)**:涉及 ORM model 变更时,必须生成迁移文件(含 up/down)
|
|
36
|
+
8. **破坏性变更协议(R4.6)**:删 ≥5 行 / 改公共接口时,grep 引用图 + 反问用户
|
|
37
|
+
|
|
38
|
+
### 上下文恢复
|
|
39
|
+
|
|
40
|
+
- **断点恢复**:新会话时 `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 自动检测当前 change 和 pending task,从上次断点继续
|
|
41
|
+
- **反重复检查**:恢复后读 `.specs/LESSONS.md` 确认不在已排除方案里(R1.8)
|
|
42
|
+
- **进度记录**:TASK.md 的 `status="done|pending"` + SUMMARY.md 就是进度,不需要额外的 PROGRESS.md 或 STATE.md
|
|
43
|
+
|
|
44
|
+
## 产物
|
|
45
|
+
|
|
46
|
+
- 代码改动
|
|
47
|
+
- `.specs/<change-id>/<task-id>-SUMMARY.md`(使用 `flow-kit/templates/SUMMARY.md`)
|
|
48
|
+
|
|
49
|
+
## 状态推进
|
|
50
|
+
|
|
51
|
+
每个 task 通过 flow-comet 的 execute 或 subagent-execute 节点执行。子代理执行时必须加载本 Skill 并回传 evidence。
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-evolve
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-evolve; scan archived changes' DESIGN.md section 9, batch-review sediment candidates, patch CONTEXT.md. Not part of the 8-node flow."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# flow-comet-evolve(横向命令 · 架构沉淀)
|
|
7
|
+
|
|
8
|
+
## 触发
|
|
9
|
+
|
|
10
|
+
用户说「同步架构 / 整理沉淀 / evolve / 同步 CONTEXT」;或 STATE.md last_evolve_at > 60 天。
|
|
11
|
+
|
|
12
|
+
> **载体说明(沿用 flow-kit 约定)**:`STATE.md` 与 `last_evolve_at` 是 flow-kit 的约定(A-evolve.md 定义:GO.md 按 last_evolve_at 提示、evolve 读/写该字段)——项目需有按 flow-kit 维护的 STATE.md;flow-comet 引擎不自动创建/维护该字段,无 STATE.md 的项目触发本命令时按「无 last_evolve_at 基线」处理(扫描全部未沉淀的归档 change 并人工确认)。
|
|
13
|
+
|
|
14
|
+
## 流程
|
|
15
|
+
|
|
16
|
+
1. 扫 `STATE.md` last_evolve_at 之后归档的 change
|
|
17
|
+
2. 只读每个 change 的 DESIGN.md § 9(禁止越界读 § 9 以外)
|
|
18
|
+
3. 聚合候选 → 贴给用户 review
|
|
19
|
+
4. 用户批准的才 patch `.specs/CONTEXT.md`(术语 / 已锁决策 / 抽象索引)
|
|
20
|
+
5. 更新 STATE.md last_evolve_at
|
|
21
|
+
|
|
22
|
+
## 边界
|
|
23
|
+
|
|
24
|
+
- 不写业务代码
|
|
25
|
+
- 不在本工作流改架构(需 A-architect 时提示用户)
|
|
26
|
+
- CONTEXT.md 更新统一走本命令或 I-intel-scan,不在 change 内直接改
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-execute
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-execute or routed by the flow-comet entry/runtime to the execute Node; complete Execute for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Execute
|
|
7
|
+
|
|
8
|
+
## Node Goal
|
|
9
|
+
|
|
10
|
+
Complete the `execute` Node for `flow-comet`.
|
|
11
|
+
|
|
12
|
+
Responsibility: 按 TASK.md 逐任务执行(**执行模式按 executionMode**:subagent 默认统一委托子代理、direct 逃生口主代理直写)。串行任务的 TDD + 6 维自查 + LESSONS 扫描 + diff 边界 verify 由执行者承担,无论哪种模式都必须加载 flow-comet-dev 协议。
|
|
13
|
+
|
|
14
|
+
In subagent mode (default) this node is a coordinator: it does not write implementation code directly — it delegates the pending serial tasks to fresh-context subagents via the Agent tool (worktree isolation), each subagent applies the full dev protocol (TDD RED/GREEN/REFACTOR, LESSONS scan, existing abstraction grep, self-review, diff boundary verification, atomic commits) and returns a Return Contract. 趟次协作:并行委托节点(subagent-execute)可多次往返——每趟委托全部依赖已满足的并行任务,本节点在趟间消化串行任务,直至两者清空。The coordinator records handoff evidence, verifies each SUMMARY, and marks tasks done in TASK.md. In direct mode (escape hatch, user-confirmed) the main agent implements serial tasks directly — see 执行模型 below.
|
|
15
|
+
|
|
16
|
+
## Guidance
|
|
17
|
+
|
|
18
|
+
### 必填段清单(结构+存在级)
|
|
19
|
+
|
|
20
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
21
|
+
|------|-------------------------------|-----------------------------------|
|
|
22
|
+
| SUMMARY.md | `## verify 输出` / `## 6 维自查`(须含实质内容)/ `## 越界检查` / `## 自检方法` | `## 做了什么` / `## 改动文件` 等(执行纪律,review 把关) |
|
|
23
|
+
|
|
24
|
+
> **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 段**——该段是 flow-comet 的强制增量(guard 校验自检方法声明)。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方必填段清单补写 `## 自检方法` 段**(声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一及降级证据),否则新 change 的 exit 会被 BLOCKED。
|
|
25
|
+
|
|
26
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
27
|
+
|
|
28
|
+
### 执行模型(按 executionMode,用户显式选择)
|
|
29
|
+
|
|
30
|
+
- **subagent(默认)**: 统一委托子代理——协调者流程(构造 handoff → Agent worktree 委托 → 收集 Return Contract → 验收标 done)
|
|
31
|
+
- **direct(逃生口,需用户显式切换)**: 主代理直接执行串行任务——但必须加载 flow-comet-dev 完整协议
|
|
32
|
+
(TDD/6 维自查/越界检查/原子 commit),SUMMARY 必填段 + `## 自检方法` 强制(guard 校验兜底)
|
|
33
|
+
- 无论哪种模式:`parallel="true"` 任务始终由 subagent-execute 并行委托,不在此节点执行。
|
|
34
|
+
|
|
35
|
+
执行模式由 `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 输出(`executionMode` / `directOverride`)决定,切换用 `node .claude/skills/flow-comet/scripts/workflow-state.mjs execution-mode <subagent|direct>`。direct 是逃生口,必须用户显式调用才生效。
|
|
36
|
+
|
|
37
|
+
### 任务范围
|
|
38
|
+
|
|
39
|
+
execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pending 任务**。
|
|
40
|
+
|
|
41
|
+
**TASK 签名校验(C3,execute 期间)**:entry execute 时记录任务集签名(行尾规范化 + 标记属性剥离);exit 时比对——execute 期间 TASK.md **只允许改开标签的标记属性**(`status` done/pending;时间戳如需记录写在开标签属性如 `completed_at`——签名剥离白名单允许;**禁止写入 action/其他 task 内容**),增删任务/改 action/改边界/改其他内容会在 exit 被 BLOCKED(签名不匹配)。回退修复任务(review/verify 发现缺陷追加)须经 review 流程追加后重新 entry execute 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
|
|
42
|
+
|
|
43
|
+
本节点**不直接写实现代码**。所有 pending 任务统一通过 Agent 工具委托 fresh-context 子代理执行(加载 flow-comet-dev + 回传 Return Contract)。
|
|
44
|
+
|
|
45
|
+
- `parallel="true"` 的 pending 任务由 subagent-execute 节点负责并行委托
|
|
46
|
+
- execute 遍历 TASK.md 时,遇到 `parallel="true" status="pending"` 的任务块应**跳过**
|
|
47
|
+
- **全 parallel 任务时 execute 不得空退出(除非显式豁免)**:guard 的 exit 校验(evidence 前置 → 串行 pending 检测 → Output Schema 产物)会 BLOCKED——「空退出」默认不可达(实测确认)。正确路径:
|
|
48
|
+
1. 正常流程下 determineNode 的 路由逻辑会**直接路由到 subagent-execute**(无需经过 execute 空退出)——协调者确认 路由逻辑生效(`NODE: subagent-execute`)后直接进入该节点
|
|
49
|
+
2. 若已进入 execute 且确认无串行任务可做:按正常 exit 流程处理(record execute evidence + 满足产物校验),需要豁免越俎代庖检测时用 `record execute '{"parallelTakeoverApproved":true}'` 显式声明;[P] 任务由 execute 完成属越权委托——新 change BLOCKED(旧 change WARN 渐进)
|
|
50
|
+
3. **显式空退出豁免(新 change 可用)**:确认全 parallel 无串行可做且无法路由时,用 `record execute '{"emptyExitApproved":true}'` 显式声明后 exit 通过(跳过串行 pending 与产物校验;防规划错误仍默认 BLOCKED——豁免须显式声明;exit 输出 EMPTY-EXIT 审计提示)
|
|
51
|
+
- determineNode 路由逻辑会优先检测依赖已满足的 parallel 任务并路由到 subagent-execute;若 determineNode 路由到了 execute,说明当前趟存在需要 execute 处理的串行任务(此时应执行而非空退出)——串行消化完成后再次路由,剩余并行任务回到 subagent-execute 的下一趟(多趟循环直至无可并行 pending 且无串行残留)
|
|
52
|
+
|
|
53
|
+
### Prerequisites
|
|
54
|
+
|
|
55
|
+
- `.specs/<change-id>/TASK.md` must exist with at least one `status="pending"` task.
|
|
56
|
+
- `.specs/<change-id>/DESIGN.md` or `DESIGN-lite.md` must exist — agent must read section 0 (tech stack) and section 0.5 (architecture alignment).
|
|
57
|
+
- `.specs/LESSONS.md` must exist (or be created from template if missing).
|
|
58
|
+
- For frontend/UI tasks: `.specs/<change-id>/UI-DESIGN.md` must exist.
|
|
59
|
+
- 若当前任务的 `<task-id>-PROGRESS.md`(位于 `.specs/<change>/`;与 Recovery 段及归档期 `*-PROGRESS.md` 扫描同口径)存在,必须先读取"已排除方案"段(R1.6 反重复),确认当前计划不在排除列表中。完成后删除该文件,有用信息迁移至 SUMMARY。
|
|
60
|
+
- 委托前按 `reference/dirty-worktree.md` 检查脏工作树(`.specs/<change-id>/` 未提交工件会触发 entry execute 的 WORKTREE WARN;verify 前为自查建议,无 guard 检查)。
|
|
61
|
+
|
|
62
|
+
### Steps(subagent 模式 · 协调者流程,统一委托子代理)
|
|
63
|
+
|
|
64
|
+
对 TASK.md 每个 pending 串行任务,协调者执行:
|
|
65
|
+
|
|
66
|
+
1. **读 task 块,构造 handoff request**:读 `<task>` XML 块(`action` / `read_files` / `write_files` / `verify` / `done`)。若内容有歧义,停下询问——不要猜。构造 handoff request 内容:task 全文 + DESIGN §0/§0.5 + AC + read/write_files 边界。运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs request <task-id>` 记录。**委托即记 request**——直接记录 result 而无对应 request 时,write_files 允许列表为空会被 BLOCKED(新 change 强制委托边界),补 request 后再重录 result 即可(执行者实证)。
|
|
67
|
+
2. **委托子代理**:用 Agent 工具(`isolation: "worktree"`)委托 fresh-context 子代理。handoff prompt 强制协议:子代理用 **Skill 工具**加载 flow-comet-dev 并按 `flow-kit/prompts/4-dev.md` 协议执行(TDD RED/GREEN/REFACTOR、LESSONS 扫描、既有抽象 grep、verify、6 维自查、越界检查、原子 commit `<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁 change-id/日期作 scope;任务号放提交正文尾注 Task: <task-id>,change-id 不入标题)),按 `flow-kit/templates/SUMMARY.md` 模板写 `.specs/<change-id>/<task-id>-SUMMARY.md`(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段),回传 Return Contract(含 commitHash + greenEvidence + completedChecks + selfReview)。**SUMMARY 自引用 hash 注**:提交内容无法包含自身 hash——若子代理 amend 提交,SUMMARY 内记录的 commitHash 为 amend 前值属预期(文件集一致即可,以实际提交对象为准)。
|
|
68
|
+
**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
|
|
69
|
+
3. **记录 handoff result**:子代理回传后,运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs result <task-id> '<JSON>'` 记录(Return Contract 含 commitHash + greenEvidence + completedChecks + selfReview)。
|
|
70
|
+
4. **验收 SUMMARY,TASK.md 标 done**:确认 SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写且**模板保真**(标题 `# SUMMARY:` / 首部 4 字段 / 段序一致)、含 `## 自检方法` 段(声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一)、verify 输出真实、6 维自查与越界检查有实质内容;通过后在 TASK.md 将任务标 `status="done"` 并加时间戳。
|
|
71
|
+
5. **下一个 pending 任务**:重复步骤 1-4。
|
|
72
|
+
|
|
73
|
+
> 原 Steps 的 TDD / LESSONS / verify / 6 维自查 / 越界检查 / commit 协议**移入 handoff prompt 作为子代理的强制协议**,协调者不亲自执行。
|
|
74
|
+
> **Return Contract 非代码任务**:纯文档 / 纯配置任务子代理回传时,`greenEvidence` 与 `redEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态(command 字段存在即可通过 W1-D 校验;redEvidence 缺失在新 change 下仍会被 W1-D 拦截,因此必须显式提供此形态而非省略字段)。
|
|
75
|
+
> **Return Contract 的 completedChecks 统一契约**:子代理回传的 `completedChecks` 必须包含 `required-skill:subagent-execute.flow-comet-dev`——execute(串行委托)与 subagent-execute(并行委托)的 handoff 统一记录在 subagent-execute 证据库(共用证据库语义),guard 的 W1-D 对全部委托结果统一校验该契约。取值与节点自证命名(本节点自身证据用的 `required-skill:execute.flow-comet-dev`,见 Required Skill Calls)无关。**格式要求**:`completedChecks` 必须是**字符串数组**(如 `["required-skill:subagent-execute.flow-comet-dev"]`)——对象数组(如 `[{id, status}]`)会被 guard 的严格比较判"缺"→ exit BLOCKED。示例:
|
|
76
|
+
>
|
|
77
|
+
> - 正确:`"completedChecks": ["required-skill:subagent-execute.flow-comet-dev"]`
|
|
78
|
+
> - 错误:`"completedChecks": ["required-skill:execute.flow-comet-dev"]` —— 按 execute 域命名会被 W1-D 拦截(exit BLOCKED),子代理必须回传统一契约值
|
|
79
|
+
> - 错误:`"completedChecks": [{"id": "required-skill:subagent-execute.flow-comet-dev", "status": "done"}]` —— 对象数组会被严格比较判"缺"(必须为字符串数组)
|
|
80
|
+
|
|
81
|
+
The full dev protocol, templates, and constraints are in:
|
|
82
|
+
- `flow-kit/prompts/4-dev.md` (DEV phase) — handoff prompt 的子代理强制协议(不再以“参照前一产物”转述——子代理必须显式按此协议执行并加载 flow-comet-dev)
|
|
83
|
+
- `flow-kit/templates/SUMMARY.md` (SUMMARY template) — 每份 `<task-id>-SUMMARY.md` 的填写模板(标题/首部/段序保真,另补 `## 自检方法` 段)
|
|
84
|
+
|
|
85
|
+
### Completion reasoning
|
|
86
|
+
|
|
87
|
+
This node is truly done when:
|
|
88
|
+
- All tasks in TASK.md have `status="done"`.
|
|
89
|
+
- Every done task has a corresponding `<task-id>-SUMMARY.md` in `.specs/<change-id>/`.
|
|
90
|
+
- Every SUMMARY.md is template-faithful (title `# SUMMARY:`, header fields, section order — per `flow-kit/templates/SUMMARY.md`, plus the `## 自检方法` section) and contains: verify output (real, not fabricated), 6-dimension self-check, and boundary check.
|
|
91
|
+
- No REQUIREMENT.md or DESIGN.md has been modified during execution.
|
|
92
|
+
- No out-of-boundary files have been changed without explicit approval.
|
|
93
|
+
|
|
94
|
+
### Red flags
|
|
95
|
+
|
|
96
|
+
- **Agent thought**: "I'll write the code first, then grep for existing abstractions." **Actual risk**: Writing code without grepping first (R6.4 violation) leads to duplicate implementations. Must grep BEFORE writing.
|
|
97
|
+
- **Agent thought**: "LESSONS scan is optional for simple tasks." **Actual risk**: Skipping LESSONS scan (R1.8 violation) means repeating known failures. Even simple tasks can hit documented pitfalls.
|
|
98
|
+
- **Agent thought**: "verify passed in my head, marking done." **Actual risk**: Marking done without running verify (R2.4 violation) means untested code enters review. Must paste real output.
|
|
99
|
+
- **Agent thought**: "I see a bug in an adjacent file, let me fix it along the way." **Actual risk**: "Fixing along the way" without a new task or CHANGE violates R7.1 (scope control). Must stop and create a new task or CHANGE.
|
|
100
|
+
- **Agent thought**: "This task is taking long, let me skip the self-review." **Actual risk**: Skipping self-review defers quality issues to the review node, where they become Critical items requiring fix tasks. Better to catch early.
|
|
101
|
+
- **Agent thought**: "这个 parallel 任务小,我顺手在主会话做了。" **Actual risk**: 违反并行委托设计——subagent-execute 节点被静默跳过,丢失并行隔离与 write_files 冲突防护;且 execute 出口的 all-tasks-done 校验会 BLOCKED(parallel 无 handoffResult)。parallel="true" 任务只能由 subagent-execute 委托。
|
|
102
|
+
|
|
103
|
+
## Entry Check
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Skill Implementation
|
|
110
|
+
|
|
111
|
+
Load `flow-comet-execute` for this Node. Operation: `require`.
|
|
112
|
+
|
|
113
|
+
The execute node loads `flow-comet-dev` for each task execution. It iterates through all pending tasks in TASK.md, applying the full dev protocol: TDD, LESSONS scan, existing abstraction grep, self-review (brooks-lint or 6-dimension quick check), diff boundary verification, and atomic commits. Each task produces a SUMMARY.md and is marked done in TASK.md.
|
|
114
|
+
|
|
115
|
+
## Required Skill Calls
|
|
116
|
+
|
|
117
|
+
| Skill | Enforcement | Reason |
|
|
118
|
+
|-------|-------------|--------|
|
|
119
|
+
| `flow-comet-dev` | Required for each task execution | Provides TDD protocol, LESSONS scan, 6-dimension self-check, diff boundary rules, schema migration, breaking change protocol |
|
|
120
|
+
|
|
121
|
+
Load `flow-comet-dev` during this Node and record completed check `required-skill:execute.flow-comet-dev`. Reason: TDD + 6 维自查 + R4.5 + R4.6
|
|
122
|
+
|
|
123
|
+
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
124
|
+
|
|
125
|
+
1. **用 Skill 工具加载** `flow-comet-dev`(本节点 Required Skill Call)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让 flow-comet-dev 指令生效的是 Skill 工具把它注入本次会话。委托子代理时,子代理同样必须用 Skill 工具加载 flow-comet-dev(按 `flow-kit/prompts/4-dev.md` 协议执行)。
|
|
126
|
+
2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load execute flow-comet-dev --prompt flow-kit/prompts/4-dev.md
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
133
|
+
|
|
134
|
+
## Augmentations
|
|
135
|
+
|
|
136
|
+
This Node has no declared augmentations.
|
|
137
|
+
|
|
138
|
+
## Output Schemas
|
|
139
|
+
|
|
140
|
+
Schema: `flowkit.execution.v1`
|
|
141
|
+
|
|
142
|
+
| Schema ID | Artifact Kind | Required | Path |
|
|
143
|
+
|-----------|--------------|----------|------|
|
|
144
|
+
| `task-summaries` | file | yes | `.specs/<change-id>/*-SUMMARY.md` (one per task) |
|
|
145
|
+
| `task-plan-updated` | file | yes | `.specs/<change-id>/TASK.md` (status="done" for all) |
|
|
146
|
+
|
|
147
|
+
Evidence: `implementation-summary` (required)
|
|
148
|
+
|
|
149
|
+
## Evidence Record
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record execute '{"summary":"All N tasks completed, each with SUMMARY.md and verify output"}'
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Guardrails
|
|
156
|
+
|
|
157
|
+
| Guardrail ID | Label | Validation Type |
|
|
158
|
+
|--------------|-------|-----------------|
|
|
159
|
+
| `build-evidence` | At least one SUMMARY.md produced | artifact-exists |
|
|
160
|
+
| `all-tasks-done` | All tasks in TASK.md have status="done"(pending 串行任务 → BLOCKED);done 任务须有对应 SUMMARY(新 change 强制 BLOCKED,旧 change WARN 渐进) | content-check |
|
|
161
|
+
| `verify-output-real` | Every SUMMARY.md has verify output (not fabricated) | 执行纪律(review 把关),guard 不校验 |
|
|
162
|
+
| `no-design-changes` | REQUIREMENT.md and DESIGN.md not modified | 执行纪律(review 把关),guard 不校验 |
|
|
163
|
+
| `self-check-method` | Every SUMMARY.md declares `## 自检方法`(brooks-review / cache-brooks / builtin-quickcheck) | W1-B 段级校验 |
|
|
164
|
+
|
|
165
|
+
## Exit Check
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit execute --apply
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
After exit, run `node .claude/skills/flow-comet/scripts/workflow-state.mjs next` to get the next node.
|
|
172
|
+
|
|
173
|
+
If the script prints `SKILL: flow-comet-subagent-execute`, load that Skill next.
|
|
174
|
+
|
|
175
|
+
## Recovery
|
|
176
|
+
|
|
177
|
+
1. Re-run entry check to confirm workflow state.
|
|
178
|
+
2. Read `.specs/<change-id>/TASK.md` — find first `status="pending"` task.
|
|
179
|
+
3. Read any existing `<task-id>-SUMMARY.md` files to confirm completed progress.
|
|
180
|
+
4. Check for `<task-id>-PROGRESS.md` files — if found, read "excluded solutions" section to avoid repeating failures (R1.6).
|
|
181
|
+
5. Resume from the first pending task. Do not repeat completed tasks.
|
|
182
|
+
6. If a PROGRESS.md exists for the current task, delete it after completion and migrate useful info to SUMMARY.md.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-health
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-health; periodic codebase health check: CONTEXT consistency, LESSONS scanning, tech-debt review, redundancy scan. Not part of the 8-node flow."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# flow-comet-health(横向命令 · 巡检)
|
|
7
|
+
|
|
8
|
+
## 触发
|
|
9
|
+
|
|
10
|
+
用户说「健康检查 / health / 体检 / 技术债扫描 / 巡检」。
|
|
11
|
+
|
|
12
|
+
## 前置依赖
|
|
13
|
+
|
|
14
|
+
- 装了 brooks-lint → 优先 `/brooks-health`(4 维综合体检;Codex 用 `$brooks-health`)
|
|
15
|
+
- 未装 brooks-lint → 用内置巡检清单降级
|
|
16
|
+
|
|
17
|
+
## 流程
|
|
18
|
+
|
|
19
|
+
1. 读 `.specs/CONTEXT.md` + `.specs/LESSONS.md` + 最近 1 份 `.specs/health/*.md`(对比基线)
|
|
20
|
+
2. 抽样 5 个最近改动频繁的 src/ 模块 + 5 个测试文件 + 最近 30 天 git log
|
|
21
|
+
3. 检查:
|
|
22
|
+
- CONTEXT 与代码一致性(既有抽象索引是否过期)
|
|
23
|
+
- LESSONS 是否需新增 / superseded
|
|
24
|
+
- 技术债项(Pain × Spread 优先级)
|
|
25
|
+
- 冗余(死代码 / 重复实现)——提示走 jscpd / knip / vulture 工具级扫描
|
|
26
|
+
4. 产出 `.specs/health/<date>.md` 报告 + 更新 CONTEXT 技术债段
|
|
27
|
+
|
|
28
|
+
## 边界
|
|
29
|
+
|
|
30
|
+
- 业务代码只读;写入仅限巡检报告(`.specs/health/<date>.md`)与 CONTEXT 技术债段——不自动改业务代码
|
|
31
|
+
- 发现的冗余/债项排入 backlog,不在本命令内修
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-integration
|
|
3
|
+
description: "flow-kit INTEGRATION 阶段协议:集成验证 + UAT + 失败诊断(≤3 轮)+ LESSONS 提名 + 归档。flow-comet verify/archive 节点的 flow-kit 增强。"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# flow-kit INTEGRATION Protocol
|
|
7
|
+
|
|
8
|
+
本 Skill 为 flow-comet 的 verify 和 archive 节点提供 flow-kit 的集成验证和归档流程。
|
|
9
|
+
|
|
10
|
+
## 加载
|
|
11
|
+
|
|
12
|
+
读取 `flow-kit/prompts/7-integration.md` 并按其执行。
|
|
13
|
+
|
|
14
|
+
### 集成验证(verify 阶段)
|
|
15
|
+
|
|
16
|
+
1. **跑全套自动化**:全量单测 + 集成测试 + 类型检查 + 构建
|
|
17
|
+
2. **引导人工 UAT**:逐条执行 TEST.md 中的 UAT 脚本
|
|
18
|
+
3. **失败诊断**:root cause → fix-plan → 回到 execute 修复 → 重跑
|
|
19
|
+
- **自动重试 ≤ 3 轮**(R2.6),超限暂停等人工决策
|
|
20
|
+
|
|
21
|
+
### LESSONS 提名(archive 前必跑)
|
|
22
|
+
|
|
23
|
+
扫描本次 change 的所有 `*-SUMMARY.md` 和遗留 `*-PROGRESS.md`,按提名条件筛选:
|
|
24
|
+
- 调试/试错耗时 > 30 分钟 → 提名
|
|
25
|
+
- 错因不限于本任务 → 提名
|
|
26
|
+
- 6 个月内有合理概率被再次尝试 → 提名
|
|
27
|
+
|
|
28
|
+
追加到 `.specs/LESSONS.md`,编号续 `L-NNN`。
|
|
29
|
+
|
|
30
|
+
### 归档(archive 阶段)
|
|
31
|
+
|
|
32
|
+
1. `.specs/<change-id>/` → `.specs/archive/<YYYY-MM-DD>-<change-id>/`
|
|
33
|
+
2. `.specs/CHANGELOG.md` 表格顶部按日期倒序插入一行
|
|
34
|
+
3. **不归档** `.specs/LESSONS.md`(项目级常驻)
|
|
35
|
+
4. DESIGN.md § 9 架构沉淀建议留待 A-evolve 批量同步
|
|
36
|
+
|
|
37
|
+
## 产物
|
|
38
|
+
|
|
39
|
+
- `.specs/<change-id>/UAT.md`
|
|
40
|
+
- `.specs/archive/<YYYY-MM-DD>-<change-id>/`
|
|
41
|
+
- 更新的 `.specs/CHANGELOG.md` 和 `.specs/LESSONS.md`
|
|
42
|
+
|
|
43
|
+
## 状态推进
|
|
44
|
+
|
|
45
|
+
归档操作必须用户确认后才执行。失败诊断的自动重试由 verify 节点管理(机器计数 verifyFailures,≤3 次,第 4 次暂停等用户决策)。
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-open
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-open or routed by the flow-comet entry/runtime to the open Node; complete Open for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Open
|
|
7
|
+
|
|
8
|
+
## Node Goal
|
|
9
|
+
|
|
10
|
+
Complete the `open` Node for `flow-comet`.
|
|
11
|
+
|
|
12
|
+
Responsibility: CHANGE 反问 + REQUIREMENT 需求分析。生成 CHANGE.md 和 REQUIREMENT.md。
|
|
13
|
+
|
|
14
|
+
## Guidance
|
|
15
|
+
|
|
16
|
+
### 必填段清单(exit guard 校验,结构+存在级)
|
|
17
|
+
|
|
18
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
19
|
+
|------|-------------------------------|-----------------------------------|
|
|
20
|
+
| CHANGE.md | `## Why(为什么做)` | `## What(做什么)` / `## 影响面` / `## 风险与未知` 等 |
|
|
21
|
+
| REQUIREMENT.md | `## 用户故事` / `## 验收准则(AC)` | `## 范围切分` / `## 非功能性需求` 等 |
|
|
22
|
+
|
|
23
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / templateSectionPatterns;「填得好不好」由 review 把关。
|
|
24
|
+
|
|
25
|
+
### 分支创建
|
|
26
|
+
|
|
27
|
+
`node .claude/skills/flow-comet/scripts/workflow-state.mjs init <id>` 会自动创建 `change/<id>` 分支(git 仓库时:当前分支非 `change/<id>` 且分支不存在 → `git checkout -b change/<id>`);**非 git 仓库跳过分支创建,纯文件模式照旧**。init 幂等:当前已在 `change/<id>` 分支时不重复创建。全流程在该分支上进行,归档收尾时合并回 main。
|
|
28
|
+
|
|
29
|
+
### CONTEXT 更新(位置纪律)
|
|
30
|
+
|
|
31
|
+
更新 `.specs/CONTEXT.md` 时**插入既有结构段内**,禁止新建尾部段:
|
|
32
|
+
|
|
33
|
+
- 术语 → 插入 `## 域语言(术语表)` 表格行;无该表格则插该段末尾
|
|
34
|
+
- 决策 → **段内**追加到 `## 已锁决策` 清单
|
|
35
|
+
- **禁止**新建 `## 术语(xxx 追加)` 类尾部段
|
|
36
|
+
|