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-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
|
+
<!-- 手写区详细协议见 GUIDANCE.md(可选阅读) -->
|
|
7
|
+
|
|
8
|
+
# Open
|
|
9
|
+
|
|
10
|
+
## Node Goal
|
|
11
|
+
|
|
12
|
+
Complete the `open` Node for `flow-comet`.
|
|
13
|
+
|
|
14
|
+
Responsibility: CHANGE 反问 + REQUIREMENT 需求分析。生成 CHANGE.md 和 REQUIREMENT.md。
|
|
15
|
+
|
|
16
|
+
## Guidance
|
|
17
|
+
|
|
18
|
+
### 必填段清单(结构+存在级)
|
|
19
|
+
|
|
20
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
21
|
+
|------|-------------------------------|-----------------------------------|
|
|
22
|
+
| CHANGE.md | `## Why(为什么做)` | `## 影响面` / `## 范围排除` / `## 风险与未知` 等 |
|
|
23
|
+
| REQUIREMENT.md | `## 用户故事` / `## 验收准则(AC)` | `## 范围切分` / `## 非功能性需求` 等 |
|
|
24
|
+
|
|
25
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / templateSectionPatterns;「填得好不好」由 review 把关。
|
|
26
|
+
|
|
27
|
+
# Open
|
|
28
|
+
|
|
29
|
+
## Node Goal
|
|
30
|
+
|
|
31
|
+
This node transforms a vague user intent into a concrete change proposal (CHANGE.md) and verifiable requirements (REQUIREMENT.md). It is the entry point of the flow-comet workflow, combining the CHANGE and REQUIREMENT phases into a single node. The output artifacts serve as the foundation for all downstream design, planning, and implementation work.
|
|
32
|
+
|
|
33
|
+
## Guidance
|
|
34
|
+
|
|
35
|
+
### Prerequisites
|
|
36
|
+
|
|
37
|
+
- No upstream artifacts required — this is the first node in the flow.
|
|
38
|
+
- If `.specs/<change-id>/` already exists for the proposed id, the agent must auto-increment (`<id>-2`, `<id>-3`) to avoid collision.
|
|
39
|
+
- If `.specs/ARCHITECTURE.md` exists, it should be read for context but is not a blocking prerequisite.
|
|
40
|
+
|
|
41
|
+
### Steps
|
|
42
|
+
|
|
43
|
+
1. **Auto-generate change-id**: Extract 2-4 kebab-case keywords from user description. Check `.specs/<id>/` does not exist. Declare the id to the user in the first message. User does not need to confirm unless they want to change it.
|
|
44
|
+
|
|
45
|
+
2. **Architecture change detection (0.4)**: Evaluate against 5 criteria (module structure impact, ADR conflict, public contract change, capacity boundary, cross-service orchestration). If hit: present 3 options (run A-architect first / continue with architecture impact statement / re-classify). If ARCHITECTURE.md missing + hit: warn user. If not hit (90% of cases): skip silently.
|
|
46
|
+
|
|
47
|
+
3. **Frontend project identification (0.5)**: Check if description contains frontend keywords (website/web/page/UI/app/dashboard etc.). If yes: mark as frontend project and proceed to 0.6. If not: skip to step 4.
|
|
48
|
+
|
|
49
|
+
4. **Visual tone preselection (0.6, frontend only)**: Present 9 style cards (from ui-ux-pro-max if installed, else from `flow-kit/reference/ui-aesthetics.md`). Give 1 preferred + 1 backup recommendation. Exclude 1-3 unsuitable styles with reasons. Wait for user selection before proceeding.
|
|
50
|
+
|
|
51
|
+
5. **Structured questioning (step 1)**: Ask "why / who / what problem / when is done" in max 3 questions per round. Never skip this — do not assume requirements. Do not mix with tone cards in the same message.
|
|
52
|
+
|
|
53
|
+
6. **Impact assessment (step 2)**: Determine if new/modified REQUIREMENT.md needed, if architecture touched, if existing ACs affected.
|
|
54
|
+
|
|
55
|
+
7. **Scope exclusion (step 3)**: Explicitly write what this change will NOT do. At least 1 item required.
|
|
56
|
+
|
|
57
|
+
8. **Generate CHANGE.md (step 4)**: Use `flow-kit/templates/CHANGE.md` template. Save to `.specs/<change-id>/CHANGE.md`. Must contain: Why / What / Impact / Scope exclusion / Acceptance line. No implementation details allowed.
|
|
58
|
+
|
|
59
|
+
9. **Path recommendation (step 5)**: Based on impact, recommend full / medium / shortest path with reasoning.
|
|
60
|
+
|
|
61
|
+
10. **REQUIREMENT phase**: After user confirms CHANGE.md:
|
|
62
|
+
- Write ACs in Given/When/Then format — each must be verifiable by one command or one manual operation.
|
|
63
|
+
- Scope split: v1 (must do) / v2 (next time) / out (never). At least 1 item in v2 and 1 in out.
|
|
64
|
+
- Extract terminology to `.specs/CONTEXT.md` (glossary + locked decisions + defaults).
|
|
65
|
+
- List non-functional requirements explicitly (write "none" if none).
|
|
66
|
+
- Stop and ask if any AC cannot be verified in one sentence.
|
|
67
|
+
|
|
68
|
+
11. **LESSONS scan**: Grep `.specs/LESSONS.md` for keywords related to this change. If active lessons hit, declare "difference is X" or "still applies, will not retry".
|
|
69
|
+
|
|
70
|
+
The full questioning protocol, anti-patterns, and templates are in:
|
|
71
|
+
- `flow-kit/prompts/0-change.md` (CHANGE phase)
|
|
72
|
+
- `flow-kit/prompts/1-requirement.md` (REQUIREMENT phase)
|
|
73
|
+
|
|
74
|
+
### Completion reasoning
|
|
75
|
+
|
|
76
|
+
This node is truly done when:
|
|
77
|
+
- `.specs/<change-id>/CHANGE.md` exists and user has confirmed it.
|
|
78
|
+
- `.specs/<change-id>/REQUIREMENT.md` exists with all ACs in Given/When/Then format.
|
|
79
|
+
- `.specs/CONTEXT.md` has been updated with at least 1 new term or decision.
|
|
80
|
+
- v1/v2/out scope split is populated in REQUIREMENT.md.
|
|
81
|
+
- At least 1 "out of scope" item exists in CHANGE.md.
|
|
82
|
+
- User has confirmed both artifacts.
|
|
83
|
+
|
|
84
|
+
### Red flags
|
|
85
|
+
|
|
86
|
+
- **Agent thought**: "User said enough, I can infer the rest." **Actual risk**: Skipping structured questioning leads to wrong requirements. Always ask, never assume.
|
|
87
|
+
- **Agent thought**: "CHANGE.md should describe how to implement." **Actual risk**: CHANGE.md is a proposal, not a design doc. Implementation details belong in DESIGN.md. Violates R3 role boundary.
|
|
88
|
+
- **Agent thought**: "No need for out-of-scope items, the scope is obvious." **Actual risk**: Without explicit scope exclusion, downstream phases will expand scope unchecked. At least 1 "out of scope" item is mandatory.
|
|
89
|
+
- **Agent thought**: "Architecture change detection is optional." **Actual risk**: Skipping 0.4 means a service-split or DB-migration-level change enters the flow without ADR alignment, causing DESIGN.md section 0.5 to be self-contradictory.
|
|
90
|
+
- **Agent thought**: "AC '界面要好看' is good enough." **Actual risk**: Non-verifiable ACs cannot be tested. Must stop and ask for measurable criteria.
|
|
91
|
+
|
|
92
|
+
## Entry Check
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry open
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Skill Implementation
|
|
99
|
+
|
|
100
|
+
The open node loads `flow-comet-change` for the CHANGE phase (structured questioning, change-id generation, architecture detection, visual tone preselection) and `flow-comet-requirement` for the REQUIREMENT phase (AC derivation, scope split, terminology extraction). It produces two artifacts in `.specs/<change-id>/` and updates the project-level `.specs/CONTEXT.md`.
|
|
101
|
+
|
|
102
|
+
## Required Skill Calls
|
|
103
|
+
|
|
104
|
+
| Skill | Enforcement | Reason |
|
|
105
|
+
|-------|-------------|--------|
|
|
106
|
+
| `flow-comet-change` | Required before CHANGE.md generation | Provides structured questioning protocol, architecture detection, and tone preselection |
|
|
107
|
+
| `flow-comet-requirement` | Required before REQUIREMENT.md generation | Provides AC format (Given/When/Then), scope split, and terminology extraction rules |
|
|
108
|
+
|
|
109
|
+
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
110
|
+
|
|
111
|
+
1. **用 Skill 工具加载** `flow-comet-change` 与 `flow-comet-requirement`(本节点 Required Skill Calls)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让这两个 skill 的指令生效的是 Skill 工具把它们注入本次会话。
|
|
112
|
+
2. 加载完成后**立即**运行声明命令,每个协议文件对应一条(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-change --prompt flow-kit/prompts/0-change.md
|
|
116
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-requirement --prompt flow-kit/prompts/1-requirement.md
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
120
|
+
|
|
121
|
+
## Output Schemas
|
|
122
|
+
|
|
123
|
+
Schema: `flowkit.intake.v1`
|
|
124
|
+
|
|
125
|
+
| Schema ID | Artifact Kind | Required | Path |
|
|
126
|
+
|-----------|--------------|----------|------|
|
|
127
|
+
| `change-doc` | file | yes | `.specs/<change-id>/CHANGE.md` |
|
|
128
|
+
| `requirement-doc` | file | yes | `.specs/<change-id>/REQUIREMENT.md` |
|
|
129
|
+
| `context-update` | file | yes | `.specs/CONTEXT.md` (append/update) |
|
|
130
|
+
|
|
131
|
+
Evidence: `intake-summary` (required)
|
|
132
|
+
|
|
133
|
+
## Evidence Record
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record open '{"summary":"CHANGE.md + REQUIREMENT.md generated, user confirmed"}'
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Guardrails
|
|
140
|
+
|
|
141
|
+
| Guardrail ID | Label | Validation Type |
|
|
142
|
+
|--------------|-------|-----------------|
|
|
143
|
+
| `intake-artifacts` | CHANGE.md + REQUIREMENT.md exist | artifact-exists |
|
|
144
|
+
| `context-updated` | CONTEXT.md has new terms/decisions | 执行纪律(review 把关),guard 不校验 |
|
|
145
|
+
| `scope-exclusion` | At least 1 out-of-scope item in CHANGE.md | 执行纪律(review 把关),guard 不校验 |
|
|
146
|
+
|
|
147
|
+
## Exit Check
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit open --apply
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
If the script prints `SKILL: flow-comet-design`, load that Skill next.
|
|
154
|
+
|
|
155
|
+
## Recovery
|
|
156
|
+
|
|
157
|
+
1. Re-run entry check to confirm workflow state.
|
|
158
|
+
2. Read `.specs/<change-id>/CHANGE.md` — if exists and confirmed, skip CHANGE phase.
|
|
159
|
+
3. Read `.specs/<change-id>/REQUIREMENT.md` — if exists and confirmed, skip REQUIREMENT phase.
|
|
160
|
+
4. Resume from the first incomplete artifact. Do not repeat confirmed phases.
|
|
161
|
+
5. If CHANGE.md exists but REQUIREMENT.md does not, continue from REQUIREMENT phase only.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-plan
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-plan or routed by the flow-comet entry/runtime to the plan Node; complete Plan for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Plan
|
|
7
|
+
|
|
8
|
+
## Node Goal
|
|
9
|
+
|
|
10
|
+
Complete the `plan` Node for `flow-comet`.
|
|
11
|
+
|
|
12
|
+
Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md。
|
|
13
|
+
|
|
14
|
+
## Guidance
|
|
15
|
+
|
|
16
|
+
### 必填段清单(结构+存在级)
|
|
17
|
+
|
|
18
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
19
|
+
|------|-------------------------------|-----------------------------------|
|
|
20
|
+
| TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 | `id` / `name` / `read_files` / `write_files` / `action` / `done` 等字段(执行纪律,review 把关) |
|
|
21
|
+
|
|
22
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
23
|
+
|
|
24
|
+
### 并行文件依赖检测(plan 出口 · 规划期自检)
|
|
25
|
+
|
|
26
|
+
在波次散文一致性、依赖图(`depends_on` 无环且引用存在)、7 字段同层,plan 出口还做文件级依赖检测:
|
|
27
|
+
|
|
28
|
+
- **写写强判**:本趟可运行的并行 pending 任务 `write_files` 有交集 → 新 change BLOCKED(消息含任务 id 对 × 重叠路径与恢复指引「补显式 depends_on 或拆为串行任务」);旧 change WARN 渐进不阻断。
|
|
29
|
+
- **读写弱判**:仅对**无显式 depends_on 关联**的并行对探测一方 `read_files` 命中对方 `write_files` → WARN 提示(建议补显式 depends_on 声明),不 BLOCK;有显式关联=依赖已声明,跳过(合法拓扑零新增告警)。
|
|
30
|
+
- **路径按声明实际解析**:不做扩展名白名单过滤——txt/log/无扩展名路径同等检出(链式重命名事故面闭合)。
|
|
31
|
+
- **并存不干扰**:伪并行 WARN(并行任务全部仅写测试产物)与 read∩write 弱判各自独立渐进提示;委托前写写拦截保持为第二道防线。
|
|
32
|
+
- **多趟语义**:任务显式声明 `depends_on`,合法性只取决于依赖图(无环且引用存在);全并行、全串行、串→并、并→串及任意混排均合法——引擎按依赖拓扑多趟分趟消化,并行任务先后位置不受限制。
|
|
33
|
+
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-plan
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-plan or routed by the flow-comet entry/runtime to the plan Node; complete Plan for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- 手写区详细协议见 GUIDANCE.md(可选阅读) -->
|
|
7
|
+
|
|
8
|
+
# Plan
|
|
9
|
+
|
|
10
|
+
## Node Goal
|
|
11
|
+
|
|
12
|
+
Complete the `plan` Node for `flow-comet`.
|
|
13
|
+
|
|
14
|
+
Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md。
|
|
15
|
+
|
|
16
|
+
## Guidance
|
|
17
|
+
|
|
18
|
+
### 必填段清单(结构+存在级)
|
|
19
|
+
|
|
20
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
21
|
+
|------|-------------------------------|-----------------------------------|
|
|
22
|
+
| TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 | `id` / `name` / `read_files` / `write_files` / `action` / `done` 等字段(执行纪律,review 把关) |
|
|
23
|
+
|
|
24
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
25
|
+
|
|
26
|
+
波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——新 change 不一致 BLOCKED(旧 change WARN 渐进)。
|
|
27
|
+
|
|
28
|
+
### 波次形态约束(依赖驱动多趟 · 规划期必守)
|
|
29
|
+
|
|
30
|
+
**约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on`,合法性只取决于依赖图本身:`depends_on` 无环且引用的任务都存在,规划即合法。全并行、全串行、串→并、并→串四种基本形态与任意混排序列(如 `S→P→S`、`P→S→P`)一律放行——引擎按依赖拓扑自动分趟(每趟委托全部依赖已满足的并行任务,趟间回串行消化),混排序列由多趟路由按依赖拓扑自动分趟消化,并行任务的先后位置不受任何限制。
|
|
31
|
+
|
|
32
|
+
**唯一硬性拦截:依赖环与缺失依赖**。任务间依赖不得成环(如 A→B→A),`depends_on` 也不得引用不存在的任务 id 或构成不可满足的依赖链;只有这两类依赖图缺陷会在规划出口被 BLOCKED 并附恢复指引——按提示调整涉环任务的 `depends_on` 后重新 exit 即可通过。
|
|
33
|
+
|
|
34
|
+
**警示**:落笔时先画依赖方向再标 [P],避免出口返工。
|
|
35
|
+
|
|
36
|
+
**理由**:引擎委托节点为多趟访问设计——按依赖分趟循环消化,序列形态自由度交给依赖声明表达。flow-kit 上游模板未载此约束,以本条为准。
|
|
37
|
+
|
|
38
|
+
# Plan
|
|
39
|
+
|
|
40
|
+
## Node Goal
|
|
41
|
+
|
|
42
|
+
This node decomposes the technical design into atomic, executable tasks with clear file boundaries, dependency declarations, and wave-based parallel execution plans. It produces TASK.md in XML format, which serves as the execution manifest for the dev and subagent-execute nodes. The quality of task decomposition directly determines implementation efficiency and boundary safety.
|
|
43
|
+
|
|
44
|
+
## Guidance
|
|
45
|
+
|
|
46
|
+
### Prerequisites
|
|
47
|
+
|
|
48
|
+
- `.specs/<change-id>/REQUIREMENT.md` must exist (from open node).
|
|
49
|
+
- `.specs/<change-id>/DESIGN.md` or `DESIGN-lite.md` must exist (from design node).
|
|
50
|
+
- For frontend/UI projects: `.specs/<change-id>/UI-DESIGN.md` must exist.
|
|
51
|
+
- The agent must read DESIGN.md section 0 (tech stack selected) — verify commands, dependency management, and directory structure must match the selected stack.
|
|
52
|
+
- The agent must NOT invent tech stack, touched modules, forbidden list, or write_files boundaries — all must come from DESIGN.md.
|
|
53
|
+
|
|
54
|
+
### Steps
|
|
55
|
+
|
|
56
|
+
1. **Artifact preflight gate**: Check all required upstream artifacts exist. If any missing, stop and output: `Rule R2.7 triggered: plan missing <artifact>. Return to <phase> first.` Do not proceed without all artifacts.
|
|
57
|
+
|
|
58
|
+
2. **Read DESIGN.md sections 0 and 0.5**: Understand the tech stack (for verify commands) and the architecture alignment (for file boundaries — touched modules, reuse targets, forbidden list).
|
|
59
|
+
|
|
60
|
+
3. **Decompose by file conflict (vertical slices)**: Split tasks by file conflict, NOT by horizontal layers. Each task should be a vertical slice (one feature through model/API/UI) not a horizontal layer (all models first, then all APIs). Target: 2-10 minutes per task in fresh context.
|
|
61
|
+
|
|
62
|
+
4. **Mark parallel tasks with [P]**: Tasks that have no file conflicts with each other get `parallel="true"`. They form the same execution wave.
|
|
63
|
+
|
|
64
|
+
5. **Declare depends_on**: Each task explicitly declares which tasks it depends on.
|
|
65
|
+
|
|
66
|
+
6. **Populate 7 required fields per task**:
|
|
67
|
+
- `id`: Format T01, T02, T02-1 etc. Continuous numbering.
|
|
68
|
+
- `name`: One sentence.
|
|
69
|
+
- `read_files`: Files the task is allowed to read. Must include reuse targets from DESIGN 0.5. Supports glob patterns.
|
|
70
|
+
- `write_files`: Files the task is allowed to create/modify/delete. Must NOT include forbidden modules from DESIGN 0.5. Strictly controlled.
|
|
71
|
+
- `action`: What to do (intent, not code).
|
|
72
|
+
- `verify`: One executable verification command (matching tech stack from DESIGN section 0).
|
|
73
|
+
- `done`: One sentence completion criteria, corresponding to an AC sub-item.
|
|
74
|
+
|
|
75
|
+
7. **Wave division**: Group tasks by dependency graph:
|
|
76
|
+
- Same layer = same wave (parallel execution).
|
|
77
|
+
- Cross layer = sequential execution.
|
|
78
|
+
- Output wave diagram: `Wave 1 (parallel): T01[P], T02[P]` etc.
|
|
79
|
+
|
|
80
|
+
8. **LESSONS scan**: Grep `.specs/LESSONS.md` for keywords related to planned file paths or actions. If active lessons hit, declare difference or confirm still applies.
|
|
81
|
+
|
|
82
|
+
The full task decomposition protocol, XML template, and constraints are in:
|
|
83
|
+
- `flow-kit/prompts/3-task.md` (TASK phase)
|
|
84
|
+
|
|
85
|
+
### Completion reasoning
|
|
86
|
+
|
|
87
|
+
This node is truly done when:
|
|
88
|
+
- `.specs/<change-id>/TASK.md` exists in XML format.
|
|
89
|
+
- At least one `<task>` block exists; every task carries a `<verify>` field (the full seven-field shape — id/name/read_files/write_files/action/verify/done — is the execution discipline, review-checked; guard enforces the subset).
|
|
90
|
+
- Every `verify` field is an executable command (not a description).
|
|
91
|
+
- Every `write_files` is strictly within DESIGN.md touched + new modules range (not in forbidden list).
|
|
92
|
+
- At least 1 task is marked `[P]` (parallel), unless all tasks are genuinely serial.
|
|
93
|
+
- Wave division diagram is clear and has no circular dependencies.
|
|
94
|
+
- Task numbering is continuous.
|
|
95
|
+
|
|
96
|
+
### Red flags
|
|
97
|
+
|
|
98
|
+
- **Agent thought**: "Split by layer first — models, then services, then endpoints." **Actual risk**: Horizontal layering creates artificial dependencies and blocks parallel execution. Always slice vertically by file conflict.
|
|
99
|
+
- **Agent thought**: "verify: tests should pass" is good enough. **Actual risk**: Vague verify commands cannot be executed. Must be specific: `pytest tests/test_x.py -v` not "tests should pass".
|
|
100
|
+
- **Agent thought**: "write_files can include any file the task might touch." **Actual risk**: Including DESIGN forbidden list modules in write_files bypasses R7.3 + R6.5 boundary enforcement. Strict control is mandatory.
|
|
101
|
+
- **Agent thought**: "All tasks are serial, no need for [P] marking." **Actual risk**: Failing to identify parallel opportunities wastes execution time. Most changes have at least some independent tasks.
|
|
102
|
+
- **Agent thought**: "read_files and write_files are the same thing." **Actual risk**: read_files includes reuse targets and reference modules; write_files is strictly the modification boundary. They serve different purposes (B3 old-project guardrail).
|
|
103
|
+
|
|
104
|
+
## Entry Check
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry plan
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Skill Implementation
|
|
111
|
+
|
|
112
|
+
The plan node loads `flow-comet-task` to perform task decomposition. It reads DESIGN.md sections 0 and 0.5 for tech stack and architecture alignment, then produces TASK.md with XML-formatted atomic tasks, wave division, and parallel markers. Each task has strict read_files/write_files boundaries derived from DESIGN.md module analysis.
|
|
113
|
+
|
|
114
|
+
## Required Skill Calls
|
|
115
|
+
|
|
116
|
+
| Skill | Enforcement | Reason |
|
|
117
|
+
|-------|-------------|--------|
|
|
118
|
+
| `flow-comet-task` | Required for task decomposition | Provides XML template, wave division protocol, and file boundary rules |
|
|
119
|
+
|
|
120
|
+
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
121
|
+
|
|
122
|
+
1. **用 Skill 工具加载** `flow-comet-task`(本节点 Required Skill Call)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让 flow-comet-task 指令生效的是 Skill 工具把它注入本次会话。
|
|
123
|
+
2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load plan flow-comet-task --prompt flow-kit/prompts/3-task.md
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
130
|
+
|
|
131
|
+
## Output Schemas
|
|
132
|
+
|
|
133
|
+
Schema: `flowkit.plan.v1`
|
|
134
|
+
|
|
135
|
+
| Schema ID | Artifact Kind | Required | Path |
|
|
136
|
+
|-----------|--------------|----------|------|
|
|
137
|
+
| `task-plan` | file | yes | `.specs/<change-id>/TASK.md` |
|
|
138
|
+
|
|
139
|
+
Evidence: `plan-summary` (required)
|
|
140
|
+
|
|
141
|
+
## Evidence Record
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record plan '{"summary":"TASK.md produced with N tasks in M waves, K parallel"}'
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Guardrails
|
|
148
|
+
|
|
149
|
+
| Guardrail ID | Label | Validation Type |
|
|
150
|
+
|--------------|-------|-----------------|
|
|
151
|
+
| `plan-artifacts` | TASK.md exists with XML tasks | artifact-exists |
|
|
152
|
+
| `task-fields-complete` | All tasks have 7 required fields | 执行纪律(review 把关),guard 不校验 |
|
|
153
|
+
| `write-files-safe` | No write_files in DESIGN forbidden list | 执行纪律(review 把关),guard 不校验 |
|
|
154
|
+
| `has-parallel` | At least 1 [P] task (if applicable) | 执行纪律(review 把关),guard 不校验 |
|
|
155
|
+
|
|
156
|
+
## Exit Check
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit plan --apply
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
If the script prints `SKILL: flow-comet-execute`, load that Skill next.
|
|
163
|
+
|
|
164
|
+
## Recovery
|
|
165
|
+
|
|
166
|
+
1. Re-run entry check to confirm workflow state.
|
|
167
|
+
2. Read `.specs/<change-id>/TASK.md` — if exists with all tasks having 7 fields and wave diagram, plan phase is done.
|
|
168
|
+
3. If TASK.md exists but incomplete (missing fields, no wave diagram), resume from the first incomplete task.
|
|
169
|
+
4. Do not repeat completed decomposition. Resume from the first incomplete artifact.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-requirement
|
|
3
|
+
description: "flow-kit REQUIREMENT 阶段协议:AC(Given/When/Then)+ v1·v2·out 范围切分 + 术语提取。flow-comet open 节点的 flow-kit 增强。"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# flow-kit REQUIREMENT Protocol
|
|
7
|
+
|
|
8
|
+
本 Skill 为 flow-comet 的 open 节点提供 flow-kit 的 REQUIREMENT 需求分析。
|
|
9
|
+
|
|
10
|
+
## 加载
|
|
11
|
+
|
|
12
|
+
读取 `flow-kit/prompts/1-requirement.md` 并按其执行。关键步骤:
|
|
13
|
+
|
|
14
|
+
1. **AC 编写**:每条 AC 使用 Given/When/Then 格式
|
|
15
|
+
2. **v1·v2·out 切分**:v1 本次必做 / v2 可推迟 / out 明确不做
|
|
16
|
+
3. **术语提取**:域语言表,写入 `.specs/CONTEXT.md`
|
|
17
|
+
4. **非功能性需求**:性能/安全/兼容性预算
|
|
18
|
+
5. **生成 REQUIREMENT.md**(使用 `flow-kit/templates/REQUIREMENT.md`)
|
|
19
|
+
|
|
20
|
+
## 产物
|
|
21
|
+
|
|
22
|
+
- `.specs/<change-id>/REQUIREMENT.md`
|
|
23
|
+
- `.specs/CONTEXT.md`(首次或需更新时)
|
|
24
|
+
|
|
25
|
+
## 状态推进
|
|
26
|
+
|
|
27
|
+
REQUIREMENT.md 是 design 节点的前置依赖。由 workflow-guard 检查产物完整性。
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-review
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-review or routed by the flow-comet entry/runtime to the review Node; complete Review for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Review
|
|
7
|
+
|
|
8
|
+
## Node Goal
|
|
9
|
+
|
|
10
|
+
Complete the `review` Node for `flow-comet`.
|
|
11
|
+
|
|
12
|
+
Responsibility: 4 轮审查(spec 合规 + 代码质量 + UI 视觉 + 可选)。生成 REVIEW.md。
|
|
13
|
+
|
|
14
|
+
This node performs a structured multi-round review of the implemented change, checking spec compliance, code quality across 6 decay dimensions, UI visual consistency (frontend only), and optional tech debt assessment. It produces REVIEW.md and generates numbered fix tasks for any Critical or Major findings. The review node is the quality gate before integration — nothing enters verify without passing this node's checks.
|
|
15
|
+
|
|
16
|
+
## Guidance
|
|
17
|
+
|
|
18
|
+
### 必填段清单(结构+存在级)
|
|
19
|
+
|
|
20
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
21
|
+
|------|-------------------------------|-----------------------------------|
|
|
22
|
+
| REVIEW.md | 文件 ≥ 100 字节;发现区条目处置标记(`[已修]` / `[升级]` / `[转待办]`——新 change 缺失 BLOCKED,旧 change WARN 渐进) | `## Critical` / `## 发现` / `## 结论` 等段(结构要求,guard 不拦段名) |
|
|
23
|
+
|
|
24
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
25
|
+
|
|
26
|
+
### 必查清单(review 逐项核对 · 执行者交付纪律)
|
|
27
|
+
|
|
28
|
+
- [ ] **工件模板保真**:每份交付工件(`*-SUMMARY.md` / TASK / CHANGE / REQUIREMENT / DESIGN)的**标题 / 首部字段 / 段序**与对应模板一致——SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写并含 `## 自检方法` 段;执行者按 `flow-kit/prompts/4-dev.md` 协议交付。
|
|
29
|
+
- [ ] **Skill 工具触发可见**:检查执行者交付的 transcript,**逐节点可见本节点 skill 用 Skill 工具加载**的触发记录——声明标记在 ≠ 已加载;只看到 `skill-load` 声明命令、看不到 Skill 工具触发 → 反馈并要求补证/重做。
|
|
30
|
+
|
|
31
|
+
### Prerequisites
|
|
32
|
+
|
|
33
|
+
- All tasks in TASK.md must have `status="done"`.
|
|
34
|
+
- `<task-id>-SUMMARY.md` must exist for every completed task.
|
|
35
|
+
- `.specs/<change-id>/REQUIREMENT.md`, `DESIGN.md`, `TASK.md` must exist.
|
|
36
|
+
- `.specs/<change-id>/TEST.md` must exist (from 5-test or produced during review).
|
|
37
|
+
- For frontend projects: `.specs/<change-id>/UI-DESIGN.md` must exist.
|
|
38
|
+
- The reviewer agent must NOT modify code directly (R3.3) — only produce reports and fix tasks.
|
|
39
|
+
|
|
40
|
+
### Steps
|
|
41
|
+
|
|
42
|
+
1. **Round 1 — Spec compliance**: For each AC in REQUIREMENT.md:
|
|
43
|
+
- Check if implemented (link to code/file).
|
|
44
|
+
- Check if tested (link to TEST.md).
|
|
45
|
+
- Check no out-of-scope content was introduced.
|
|
46
|
+
- Check no unplanned features were added.
|
|
47
|
+
- Check no DESIGN.md architecture was violated.
|
|
48
|
+
- Check every `*-SUMMARY.md` is **模板保真**(标题 `# SUMMARY:` / 首部 4 字段 / 段序一致,含 `## 自检方法` 段)——见下方「必查清单」。
|
|
49
|
+
|
|
50
|
+
2. **Round 1.5 — Contract consistency check (O-8)**: For changes touching API contracts, state machines, or form validation, verify frontend/backend consistency — this catches silent enum/value mismatches that unit tests on each side miss:
|
|
51
|
+
- **Enum/state values**: Backend status/type enums must match frontend maps (e.g. `ScheduleConfig.status` 0/2/3/4 vs frontend `SCHEDULE_STATUS_MAP`) — grep both sides, confirm the same values mean the same thing.
|
|
52
|
+
- **Field names**: API response fields must match frontend TypeScript types (no silent rename / nested-vs-flat mismatch).
|
|
53
|
+
- **Validation rules**: min/max/required conditions must align between backend Pydantic `Field(ge=...)` / conditional checks and frontend form rules (e.g. required only when a switch is enabled).
|
|
54
|
+
- Record any mismatch as a Major finding with both file:line references (frontend + backend).
|
|
55
|
+
|
|
56
|
+
3. **Round 2 — Code quality (6 decay risks)**: Diagnose the diff across 6 dimensions from brooks-lint:
|
|
57
|
+
- **R1 Cognitive Overload**: Is the code hard to understand? (>50 line functions, >3 nesting levels)
|
|
58
|
+
- **R2 Change Propagation**: Does changing one thing break unrelated parts?
|
|
59
|
+
- **R3 Knowledge Duplication**: Is the same business rule/constant expressed in multiple places? (Conceptual, not literal code duplication)
|
|
60
|
+
- **R4 Accidental Complexity**: Is the code more complex than the problem requires?
|
|
61
|
+
- **R5 Dependency Disorder**: Do dependencies flow consistently (high -> low layer)?
|
|
62
|
+
- **R6 Domain Model Distortion**: Does the code faithfully reflect the business domain?
|
|
63
|
+
|
|
64
|
+
Prefer `/brooks-review` (Claude Code; Codex: `$brooks-review` / `/use brooks-review` — brooks-lint installed) and paste output verbatim. The built-in 6-dimension quick check is a FALLBACK ONLY when brooks-lint is genuinely unavailable (e.g. subagent environment without the plugin) — then diagnose with 4-element format (Symptom/Source/Consequence/Remedy) with file:line references and book citations, and record "brooks-lint unavailable" in the review.
|
|
65
|
+
|
|
66
|
+
3.5. **Round 2.0 — TEST.md 5-round pyramid completeness**: Before code quality, verify TEST.md:
|
|
67
|
+
- All 5 rounds have clear status (no unfilled).
|
|
68
|
+
- Skipped rounds have reasons.
|
|
69
|
+
- Round 1 (functional): every AC has coverage.
|
|
70
|
+
- Round 2 (performance): if required, has actual/budget/baseline columns.
|
|
71
|
+
- Round 3 (security): if required, has dependency/secret/SAST/OWASP records.
|
|
72
|
+
- Round 4 (compatibility): if required, has browser matrix/migration/cross-version.
|
|
73
|
+
- Round 5 (observability): if required, has log/metric/alert/health check.
|
|
74
|
+
- Any gap -> mark Critical, return to 5-test first.
|
|
75
|
+
|
|
76
|
+
4. **Round 2.2 — Architecture dependency check (large changes)**: If change adds top-level modules, has dangerous imports, introduces new middleware/services, or spans >= 5 modules: run `/brooks-audit` (Codex: `$brooks-audit`; or draw simplified Mermaid dependency graph). Check for circular dependencies, reverse dependencies, cross-boundary imports.
|
|
77
|
+
|
|
78
|
+
5. **Round 3 — UI visual review (frontend only)**: If change has UI-DESIGN.md or touches UI files:
|
|
79
|
+
- **3.1 Design tokens**: All colors from UI-DESIGN.md CSS variables? No hardcoded hex/font-size/spacing?
|
|
80
|
+
- **3.2 Anti-pattern scan**: Check against `ui-anti-patterns.md` (fonts, colors, shadows, borders, animations, layout, copy, components).
|
|
81
|
+
- **3.3 Visual north star**: If you only saw the implementation screenshot, would you recognize the declared visual tone?
|
|
82
|
+
- **3.4 Accessibility quick check**: WCAG 2.1 AA contrast, keyboard reachable, focus ring visible, reduced-motion support, form label association, image alt text.
|
|
83
|
+
|
|
84
|
+
6. **Round 4 — Optional supplements**:
|
|
85
|
+
- **4.1 Tech debt assessment**: If milestone/quarterly release, run `/brooks-debt` (Codex: `$brooks-debt`). Categorize findings into Critical (fix now) / Scheduled (next 1-3 iterations) / Monitored (record only).
|
|
86
|
+
- **4.2 Cross-model spot-check**: If involves security/auth/concurrency/single function >80 lines/coverage drop: run same review with another model, record divergence.
|
|
87
|
+
|
|
88
|
+
7. **Severity grading**: Each finding gets:
|
|
89
|
+
- Critical (must fix: data corruption, security, AC not met)
|
|
90
|
+
- Major (should fix: design issues, significant regression)
|
|
91
|
+
- Minor (optional: naming, style, small refactor)
|
|
92
|
+
|
|
93
|
+
8. **Generate fix tasks**: For all Critical and decided-to-fix Major findings, append to `.specs/<change-id>/TASK.md` as numbered fix tasks with full 7 fields — 追加到 TASK.md 的 `## Fix 任务` 段内(**禁止文件尾追加**), then trigger return to execute node.
|
|
94
|
+
|
|
95
|
+
9. **Disposition markers (problem-handling principle)**: Every finding entry in the `## 发现` section of REVIEW.md — including Minor — must carry a **disposition marker** so findings never silently disappear after being recorded:
|
|
96
|
+
- `[已修]` — fixed via a fix task (linked in the entry)
|
|
97
|
+
- `[升级]` — escalated to the user for a decision (accept + reason recorded)
|
|
98
|
+
- `[转待办]` — deferred to `.specs/<change-id>/KNOWN-ISSUES.md` at archive time
|
|
99
|
+
The exit guard structurally checks these markers on the findings area (missing marker → non-blocking warning, to avoid deadlocking legacy reviews; add markers to clear it).
|
|
100
|
+
|
|
101
|
+
The full review protocol, templates, and checklists are in:
|
|
102
|
+
- `flow-kit/prompts/6-review.md` (REVIEW phase)
|
|
103
|
+
- `flow-kit/prompts/5-test.md` (TEST phase, for test pyramid completeness)
|
|
104
|
+
|
|
105
|
+
### Completion reasoning
|
|
106
|
+
|
|
107
|
+
This node is truly done when:
|
|
108
|
+
- `.specs/<change-id>/REVIEW.md` exists with all 3 mandatory rounds completed.
|
|
109
|
+
- Every finding has a severity label, file:line reference, and a disposition marker (`[已修]` / `[升级]` / `[转待办]`).
|
|
110
|
+
- All Critical items are either fixed (fix tasks generated) or explicitly accepted with user confirmation.
|
|
111
|
+
- 0 unacknowledged Critical items remain.
|
|
112
|
+
- TEST.md 5-round pyramid completeness has been verified.
|
|
113
|
+
- No code was directly modified by the reviewer (R3.3).
|
|
114
|
+
|
|
115
|
+
### Red flags
|
|
116
|
+
|
|
117
|
+
- **Agent thought**: "Code looks good, no issues found." **Actual risk**: Concluding without file:line references means the review was superficial. Every finding must point to specific code.
|
|
118
|
+
- **Agent thought**: "TEST.md exists, that's enough." **Actual risk**: Not checking test pyramid completeness means gaps in test coverage go undetected. Must verify all 5 rounds have clear status.
|
|
119
|
+
- **Agent thought**: "I'll fix this small issue directly." **Actual risk**: Reviewer modifying code violates R3.3. Must generate fix tasks instead.
|
|
120
|
+
- **Agent thought**: "Round 3 (UI) is optional." **Actual risk**: For frontend projects with UI changes, Round 3 is mandatory. Only non-frontend projects skip it.
|
|
121
|
+
- **Agent thought**: "6-dimension review is just a checklist." **Actual risk**: Without file:line references and book citations (when using built-in path), the review lacks rigor and fixability.
|
|
122
|
+
- **Agent thought**: "I'll record this Minor and move on." **Actual risk**: Findings (especially Minor) that are recorded without a disposition marker silently disappear — the exit guard warns on missing markers; every finding must be `[已修]`, `[升级]` (user decision), or `[转待办]` (tracked for archive).
|
|
123
|
+
|
|
124
|
+
## Entry Check
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry review
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Skill Implementation
|
|
131
|
+
|
|
132
|
+
Load `flow-comet-review` for this Node. Operation: `require`.
|
|
133
|
+
|
|
134
|
+
The review node performs a structured 4-round review: spec compliance (Round 1), code quality with 6 decay dimensions + TEST.md completeness + architecture dependency check (Round 2), UI visual review for frontend (Round 3), and optional tech debt/cross-model supplements (Round 4). It produces REVIEW.md and generates fix tasks for Critical/Major findings. The reviewer does not modify code directly.
|
|
135
|
+
|
|
136
|
+
## Required Skill Calls
|
|
137
|
+
|
|
138
|
+
| Skill | Enforcement | Reason |
|
|
139
|
+
|-------|-------------|--------|
|
|
140
|
+
| `flow-comet-test` | Required for test pyramid completeness check | Verifies TEST.md 5-round status before code quality review |
|
|
141
|
+
| `/brooks-review` | Preferred if installed | Provides book-backed 6-dimension code quality diagnosis |
|
|
142
|
+
| `/brooks-audit` | Conditional (large changes) | Provides architecture dependency graph with cycle detection |
|
|
143
|
+
| `/brooks-debt` | Conditional (milestones) | Provides tech debt prioritization with Pain x Spread |
|
|
144
|
+
|
|
145
|
+
Load `flow-comet-test` during this Node and record completed check `required-skill:review.flow-comet-test`. Reason: 测试金字塔完整性
|
|
146
|
+
|
|
147
|
+
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
148
|
+
|
|
149
|
+
1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-review`)无需重复加载,仅需运行下方对应声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-test` 为本节点 Required Skill Call,每次 review **必须用 Skill 工具加载**。
|
|
150
|
+
2. 加载完成后**立即**运行声明命令,每个协议文件对应一条(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load review flow-comet-review --prompt flow-kit/prompts/6-review.md
|
|
154
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load review flow-comet-test --prompt flow-kit/prompts/5-test.md
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
158
|
+
|
|
159
|
+
## Augmentations
|
|
160
|
+
|
|
161
|
+
This Node has no declared augmentations.
|
|
162
|
+
|
|
163
|
+
## Output Schemas
|
|
164
|
+
|
|
165
|
+
Schema: `flowkit.review.v1`
|
|
166
|
+
|
|
167
|
+
| Schema ID | Artifact Kind | Required | Path |
|
|
168
|
+
|-----------|--------------|----------|------|
|
|
169
|
+
| `review-doc` | file | yes | `.specs/<change-id>/REVIEW.md` |
|
|
170
|
+
| `fix-tasks` | file | conditional | `.specs/<change-id>/TASK.md` (numbered fix tasks appended) |
|
|
171
|
+
|
|
172
|
+
Evidence: `review-summary` (required)
|
|
173
|
+
|
|
174
|
+
## Evidence Record
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record review '{"summary":"REVIEW.md produced: N Critical, M Major, K Minor. X fix tasks generated."}'
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Guardrails
|
|
181
|
+
|
|
182
|
+
| Guardrail ID | Label | Validation Type |
|
|
183
|
+
|--------------|-------|-----------------|
|
|
184
|
+
| `review-evidence` | REVIEW.md exists | artifact-exists |
|
|
185
|
+
| `critical-resolved` | 0 unacknowledged Critical items | 执行纪律(review 把关),guard 不校验 |
|
|
186
|
+
| `no-code-changes` | Reviewer did not modify code files | 执行纪律(review 把关),guard 不校验 |
|
|
187
|
+
| `test-pyramid-checked` | TEST.md 5-round completeness verified | 执行纪律(review 把关),guard 不校验 |
|
|
188
|
+
|
|
189
|
+
## Exit Check
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit review --apply
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
If the script prints `SKILL: flow-comet-verify`, load that Skill next.
|
|
196
|
+
|
|
197
|
+
## Recovery
|
|
198
|
+
|
|
199
|
+
1. Re-run entry check to confirm workflow state.
|
|
200
|
+
2. Read `.specs/<change-id>/REVIEW.md` — if exists with all rounds completed and Critical resolved, review is done.
|
|
201
|
+
3. If REVIEW.md exists but incomplete, check which rounds are missing and resume from there.
|
|
202
|
+
4. If Critical items were found but fix tasks not yet generated, generate them now.
|
|
203
|
+
5. If fix tasks were generated but not executed, return to execute node.
|
|
204
|
+
6. Do not repeat completed review rounds.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: flow-comet-subagent-execute
|
|
3
|
+
description: "Use only when explicitly invoked as /flow-comet-subagent-execute or routed by the flow-comet entry/runtime to the subagent-execute Node; complete Subagent Execute for flow-comet. Do not use for ordinary standalone tasks or as the workflow entry."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Subagent Execute
|
|
7
|
+
|
|
8
|
+
## Node Goal
|
|
9
|
+
|
|
10
|
+
Complete the `subagent-execute` Node for `flow-comet`.
|
|
11
|
+
|
|
12
|
+
Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-dev 并回传 evidence。
|
|
13
|
+
|
|
14
|
+
职责分工:execute 节点负责**串行委托**(非 parallel 任务,一次一个),本节点负责**并行委托**(`parallel="true"` 任务,同 wave 多任务同时发)。两者共用同一委托证据库(handoff 记录在 subagent-execute evidence)。
|
|
15
|
+
|
|
16
|
+
## Guidance
|
|
17
|
+
|
|
18
|
+
### 必填段清单(结构+存在级)
|
|
19
|
+
|
|
20
|
+
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
21
|
+
|------|-------------------------------|-----------------------------------|
|
|
22
|
+
| SUMMARY.md | `## verify 输出` / `## 6 维自查`(须含实质内容)/ `## 越界检查` / `## 自检方法` | `## 做了什么` / `## 改动文件` 等(执行纪律,review 把关) |
|
|
23
|
+
|
|
24
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
25
|
+
|
|
26
|
+
### 委托前写写拦截(第二道锚保持)
|
|
27
|
+
|
|
28
|
+
plan 出口已做文件级依赖检测(写写强判:新 change BLOCKED / 旧 change WARN;读写弱判:无显式 depends_on 关联对 WARN;伪并行 WARN 并存渐进)——委托前既有 write∩write 拦截**保持为第二道防线**(`BLOCKED: parallel tasks write_files 冲突`,行为与消息既有语义不变)。并行委托前仍校验本趟并行任务的 `write_files` 交集,plan 出口检测的提示/拦截不改变委托前拦截。
|
|
29
|
+
|