cc-devflow 4.1.4 → 4.1.6

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 (128) hide show
  1. package/.claude/CLAUDE.md +87 -1183
  2. package/.claude/commands/core/architecture.md +2 -2
  3. package/.claude/commands/core/guidelines.md +2 -2
  4. package/.claude/commands/core/roadmap.md +4 -4
  5. package/.claude/commands/core/style.md +40 -268
  6. package/.claude/commands/flow/CLAUDE.md +28 -0
  7. package/.claude/commands/flow/archive.md +2 -2
  8. package/.claude/commands/flow/checklist.md +9 -251
  9. package/.claude/commands/flow/clarify.md +9 -127
  10. package/.claude/commands/flow/constitution.md +1 -1
  11. package/.claude/commands/flow/context.md +1 -1
  12. package/.claude/commands/flow/dev.md +19 -395
  13. package/.claude/commands/flow/fix.md +1 -6
  14. package/.claude/commands/flow/ideate.md +13 -13
  15. package/.claude/commands/flow/init.md +19 -41
  16. package/.claude/commands/flow/new.md +12 -268
  17. package/.claude/commands/flow/quality.md +10 -153
  18. package/.claude/commands/flow/release.md +18 -131
  19. package/.claude/commands/flow/restart.md +15 -16
  20. package/.claude/commands/flow/spec.md +14 -164
  21. package/.claude/commands/flow/status.md +12 -12
  22. package/.claude/commands/flow/update.md +4 -4
  23. package/.claude/commands/flow/upgrade.md +6 -6
  24. package/.claude/commands/flow/verify.md +19 -78
  25. package/.claude/commands/flow/workspace.md +3 -20
  26. package/.claude/docs/guides/INIT_TROUBLESHOOTING.md +7 -7
  27. package/.claude/docs/guides/NEW_TROUBLESHOOTING.md +44 -96
  28. package/.claude/docs/guides/ROADMAP_TROUBLESHOOTING.md +1 -1
  29. package/.claude/docs/guides/TASK_COMPLETION_MARKING.md +5 -5
  30. package/.claude/docs/guides/TEAM_MODE_GUIDE.md +0 -1
  31. package/.claude/docs/templates/ATTEMPT_TEMPLATE.md +1 -1
  32. package/.claude/docs/templates/BACKLOG_TEMPLATE.md +3 -3
  33. package/.claude/docs/templates/CLARIFICATION_REPORT_TEMPLATE.md +5 -5
  34. package/.claude/docs/templates/ERROR_LOG_TEMPLATE.md +2 -2
  35. package/.claude/docs/templates/INIT_FLOW_TEMPLATE.md +3 -3
  36. package/.claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md +33 -64
  37. package/.claude/docs/templates/RESEARCH_TEMPLATE.md +3 -3
  38. package/.claude/docs/templates/ROADMAP_DIALOGUE_TEMPLATE.md +2 -2
  39. package/.claude/docs/templates/ROADMAP_TEMPLATE.md +2 -2
  40. package/.claude/docs/templates/STYLE_TEMPLATE.md +3 -3
  41. package/.claude/docs/templates/UI_PROTOTYPE_TEMPLATE.md +8 -9
  42. package/.claude/guides/workflow-guides/flow-orchestrator.md +31 -265
  43. package/.claude/hooks/CLAUDE.md +1 -1
  44. package/.claude/hooks/checklist-gate.js +4 -4
  45. package/.claude/hooks/inject-agent-context.ts +2 -2
  46. package/.claude/hooks/teammate-idle-hook.ts +1 -1
  47. package/.claude/rules/devflow-conventions.md +2 -93
  48. package/.claude/scripts/CLAUDE.md +1 -4
  49. package/.claude/scripts/calculate-checklist-completion.sh +2 -2
  50. package/.claude/scripts/check-prerequisites.sh +2 -2
  51. package/.claude/scripts/checklist-errors.sh +4 -4
  52. package/.claude/scripts/common.sh +12 -147
  53. package/.claude/scripts/flow-quality-full.sh +5 -5
  54. package/.claude/scripts/flow-quality-quick.sh +4 -4
  55. package/.claude/scripts/flow-workspace-init.sh +2 -2
  56. package/.claude/scripts/generate-clarification-report.sh +4 -4
  57. package/.claude/scripts/recover-workflow.sh +70 -73
  58. package/.claude/scripts/run-quality-gates.sh +1 -1
  59. package/.claude/scripts/setup-epic.sh +2 -2
  60. package/.claude/scripts/setup-ralph-loop.sh +2 -2
  61. package/.claude/scripts/validate-research.sh +1 -1
  62. package/.claude/scripts/verify-setup.sh +1 -1
  63. package/.claude/skills/cc-devflow-orchestrator/SKILL.md +88 -108
  64. package/.claude/skills/workflow/CLAUDE.md +24 -0
  65. package/.claude/skills/workflow/flow-dev/CLAUDE.md +14 -76
  66. package/.claude/skills/workflow/flow-dev/SKILL.md +29 -67
  67. package/.claude/skills/workflow/flow-dev/context.jsonl +4 -8
  68. package/.claude/skills/workflow/flow-init/SKILL.md +23 -186
  69. package/.claude/skills/workflow/flow-init/assets/RESEARCH_TEMPLATE.md +1 -1
  70. package/.claude/skills/workflow/flow-init/context.jsonl +3 -3
  71. package/.claude/skills/workflow/flow-init/scripts/check-prerequisites.sh +1 -1
  72. package/.claude/skills/workflow/flow-init/scripts/create-requirement.sh +15 -134
  73. package/.claude/skills/workflow/flow-init/scripts/validate-research.sh +1 -1
  74. package/.claude/skills/workflow/flow-release/SKILL.md +20 -110
  75. package/.claude/skills/workflow/flow-release/context.jsonl +5 -7
  76. package/.claude/skills/workflow/flow-spec/CLAUDE.md +15 -101
  77. package/.claude/skills/workflow/flow-spec/SKILL.md +15 -518
  78. package/.claude/skills/workflow/flow-spec/context.jsonl +5 -7
  79. package/.claude/skills/workflow/flow-verify/CLAUDE.md +10 -0
  80. package/.claude/skills/workflow/flow-verify/SKILL.md +53 -0
  81. package/.claude/skills/workflow/flow-verify/context.jsonl +5 -0
  82. package/.claude/skills/workflow.yaml +72 -270
  83. package/CHANGELOG.md +72 -0
  84. package/README.md +91 -69
  85. package/README.zh-CN.md +90 -67
  86. package/bin/harness.js +22 -0
  87. package/docs/commands/README.md +34 -38
  88. package/docs/commands/README.zh-CN.md +34 -36
  89. package/docs/commands/core-roadmap.md +2 -2
  90. package/docs/commands/core-roadmap.zh-CN.md +2 -2
  91. package/docs/commands/core-style.md +29 -381
  92. package/docs/commands/core-style.zh-CN.md +29 -381
  93. package/docs/commands/flow-init.md +10 -10
  94. package/docs/commands/flow-init.zh-CN.md +11 -11
  95. package/docs/commands/flow-new.md +25 -260
  96. package/docs/commands/flow-new.zh-CN.md +26 -257
  97. package/docs/guides/getting-started.md +16 -15
  98. package/docs/guides/getting-started.zh-CN.md +10 -12
  99. package/lib/compiler/__tests__/manifest.test.js +156 -0
  100. package/lib/compiler/__tests__/parser.test.js +21 -0
  101. package/lib/compiler/index.js +17 -1
  102. package/lib/compiler/manifest.js +68 -6
  103. package/lib/compiler/parser.js +5 -0
  104. package/lib/harness/CLAUDE.md +21 -0
  105. package/lib/harness/cli.js +208 -0
  106. package/lib/harness/index.js +16 -0
  107. package/lib/harness/operations/dispatch.js +285 -0
  108. package/lib/harness/operations/init.js +48 -0
  109. package/lib/harness/operations/janitor.js +74 -0
  110. package/lib/harness/operations/pack.js +100 -0
  111. package/lib/harness/operations/plan.js +29 -0
  112. package/lib/harness/operations/release.js +83 -0
  113. package/lib/harness/operations/resume.js +44 -0
  114. package/lib/harness/operations/verify.js +163 -0
  115. package/lib/harness/planner.js +141 -0
  116. package/lib/harness/schemas.js +108 -0
  117. package/lib/harness/store.js +240 -0
  118. package/package.json +9 -1
  119. package/.claude/scripts/flow-workspace-start.sh +0 -217
  120. package/.claude/scripts/flow-workspace-switch.sh +0 -234
  121. package/.claude/skills/domain/using-git-worktrees/SKILL.md +0 -252
  122. package/.claude/skills/domain/using-git-worktrees/assets/SHELL_ALIASES.md +0 -133
  123. package/.claude/skills/domain/using-git-worktrees/context.jsonl +0 -4
  124. package/.claude/skills/domain/using-git-worktrees/scripts/worktree-cleanup.sh +0 -218
  125. package/.claude/skills/domain/using-git-worktrees/scripts/worktree-create.sh +0 -232
  126. package/.claude/skills/domain/using-git-worktrees/scripts/worktree-list.sh +0 -130
  127. package/.claude/skills/domain/using-git-worktrees/scripts/worktree-status.sh +0 -140
  128. package/.claude/skills/domain/using-git-worktrees/scripts/worktree-switch.sh +0 -70
@@ -1,103 +1,17 @@
1
- # flow-spec/ - Unified Specification Skill
2
-
3
- > L2 | 父级: `.claude/skills/workflow/CLAUDE.md`
4
-
5
- ## Purpose
6
-
7
- 统一规格阶段,合并 flow-prd/flow-tech/flow-ui/flow-epic 为单一命令。支持 Team Mode 并行协作 (v4.7)。
8
-
9
- ## Members
10
-
11
- | File | Purpose | Lines |
12
- |------|---------|-------|
13
- | `SKILL.md` | 核心指令:执行流程、模式、错误处理 | ~250 |
14
- | `context.jsonl` | 上下文注入定义 | ~10 |
15
- | `team-config.json` | Team Mode 配置:成员、工作流、协商协议 [v4.7] | ~165 |
16
- | `scripts/entry-gate.sh` | 统一入口检查 | ~150 |
17
- | `scripts/parallel-orchestrator.sh` | 并行调度逻辑文档 | ~200 |
18
- | `scripts/exit-gate.sh` | 统一出口检查 | ~180 |
19
- | `scripts/team-init.sh` | Team Mode 初始化脚本 [v4.7] | ~190 |
20
- | `scripts/team-communication.sh` | Team 通信协议脚本 [v4.7] | ~280 |
21
-
22
- ## Execution Flow
23
-
24
- ```
25
- PRD (sequential) → Tech + UI (parallel) → Epic (sequential)
26
- ```
27
-
28
- ## Mode Matrix
29
-
30
- | Mode | Flags | Agents |
31
- |------|-------|--------|
32
- | Full | (default) | PRD + Tech + UI + Epic |
33
- | Quick | `--skip-tech --skip-ui` | PRD + Epic |
34
- | Backend | `--skip-ui` | PRD + Tech + Epic |
35
- | Frontend | `--skip-tech` | PRD + UI + Epic |
36
-
37
- ## Agent References
38
-
39
- 复用现有 agent 指令:
40
- - `flow-prd/references/prd-writer.md`
41
- - `flow-tech/references/tech-architect.md`
42
- - `flow-ui/references/ui-designer.md`
43
- - `flow-epic/references/planner.md`
44
-
45
- ## Team Mode (v4.7)
46
-
47
- ### 执行模式检测
48
-
49
- | Mode | Flags | Execution |
50
- |------|-------|-----------|
51
- | Team (Full) | (default) | 并行 Team 协作 |
52
- | Subagent (Quick) | `--skip-tech --skip-ui` | 传统 Subagent |
53
- | Subagent (Backend) | `--skip-ui` | 传统 Subagent |
54
- | Subagent (Frontend) | `--skip-tech` | 传统 Subagent |
55
-
56
- ### team-config.json
57
-
58
- 定义 spec-design-team 的完整配置:
59
-
60
- - **members**: 4 个 Agent (prd-writer, tech-architect, ui-designer, planner)
61
- - **workflow.stages**: 3 阶段执行流程
62
- - **communication.negotiate_topics**: 5 个协商主题 (api_format, field_naming, auth_strategy, state_management, component_granularity)
63
- - **quality_gates**: 入口/出口检查配置
64
- - **error_handling**: 阶段失败处理策略
65
-
66
- ### scripts/team-init.sh
67
-
68
- Team Mode 初始化脚本,提供:
69
-
70
- - `detect`: 检测执行模式 (team/subagent)
71
- - `init`: 初始化 Team 状态到 orchestration_status.json
72
- - `config`: 输出 Team 配置 JSON
73
-
74
- ### scripts/team-communication.sh
75
-
76
- Team 通信协议脚本,提供:
77
-
78
- - `init`: 初始化 design_decisions.md
79
- - `record`: 记录设计决策
80
- - `template`: 获取协商消息模板
81
- - `participants`: 获取主题参与者
82
- - `owner`: 获取决策所有者
83
- - `example-api`: API 格式协商示例
84
- - `example-state`: 状态管理协商示例
85
-
86
- ### SendMessage 协商协议 (v4.7)
87
-
88
- Team Mode 下 tech-architect 和 ui-designer 通过 SendMessage 工具进行实时协商:
89
-
90
- | Topic | Initiator | Decision Owner | 协商内容 |
91
- |-------|-----------|----------------|----------|
92
- | api_format | tech-architect | tech-architect | REST/GraphQL, 分页, 错误格式 |
93
- | field_naming | tech-architect | tech-architect | camelCase/snake_case, 字段命名 |
94
- | auth_strategy | tech-architect | tech-architect | JWT/Session/OAuth |
95
- | state_management | ui-designer | ui-designer | Zustand/Redux/Context |
96
-
97
- 协商结果记录到 `devflow/requirements/{REQ}/research/design_decisions.md`。
98
-
99
- 详细协商消息模板见 `SKILL.md` Stage 2 Negotiate Protocol 部分。
100
-
101
- ---
1
+ # flow-spec/
2
+ > L2 | 父级: /Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/.claude/skills/workflow/CLAUDE.md
3
+
4
+ 成员清单
5
+ SKILL.md: flow:spec 的核心指令,定义 harness:plan 任务清单生成流程。
6
+ context.jsonl: flow-spec 上下文注入定义(context-package/task-manifest/harness-state)。
7
+ team-config.json: Team 模式配置资产(兼容保留,当前主链不依赖)。
8
+ scripts/entry-gate.sh: 旧入口脚本资产(兼容保留)。
9
+ scripts/parallel-orchestrator.sh: 旧并行编排脚本资产(兼容保留)。
10
+ scripts/exit-gate.sh: 旧出口脚本资产(兼容保留)。
11
+ scripts/team-init.sh: Team 初始化脚本资产(兼容保留)。
12
+ scripts/team-communication.sh: 旧 Team 通信脚本资产(兼容保留)。
13
+ scripts/test-team-mode.sh: Team 模式测试脚本资产(兼容保留)。
14
+
15
+ 法则: 成员完整·一行一文件·父级链接·技术词前置
102
16
 
103
17
  [PROTOCOL]: 变更时更新此头部,然后检查 CLAUDE.md
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: flow-spec
3
- description: 'Unified specification phase: PRD Tech+UI (parallel) Epic/Tasks. Usage: /flow-spec "REQ-123" [--skip-tech] [--skip-ui]'
3
+ description: 'Generate and refresh task-manifest for a requirement. Use when converting requirement context into dependency-aware executable tasks.'
4
4
  ---
5
5
 
6
6
  # Flow-Spec Skill
@@ -9,537 +9,34 @@ description: 'Unified specification phase: PRD → Tech+UI (parallel) → Epic/T
9
9
 
10
10
  ## Purpose
11
11
 
12
- 统一规格阶段,合并 flow-prd/flow-tech/flow-ui/flow-epic 为单一命令,内部并行调度 Agent。
12
+ 将需求上下文转换为 `task-manifest.json`,作为后续执行唯一任务源。
13
13
 
14
14
  ## Input Format
15
15
 
16
16
  ```bash
17
- # Full Mode (默认)
18
- /flow-spec "REQ_ID"
19
-
20
- # Quick Mode (小需求)
21
- /flow-spec "REQ_ID" --skip-tech --skip-ui
22
-
23
- # Backend Only
24
- /flow-spec "REQ_ID" --skip-ui
25
-
26
- # Frontend Only
27
- /flow-spec "REQ_ID" --skip-tech
28
- ```
29
-
30
- ## Mode Matrix
31
-
32
- | Mode | Command | Agents | Execution |
33
- |------|---------|--------|-----------|
34
- | Full | `/flow-spec` | PRD + Tech + UI + Epic | **Team Mode** (v4.7) |
35
- | Quick | `--skip-tech --skip-ui` | PRD + Epic | Subagent Mode |
36
- | Backend | `--skip-ui` | PRD + Tech + Epic | Subagent Mode |
37
- | Frontend | `--skip-tech` | PRD + UI + Epic | Subagent Mode |
38
-
39
- ## Execution Mode Detection (v4.7)
40
-
41
- ```yaml
42
- Mode Detection:
43
- if (--skip-tech OR --skip-ui):
44
- mode: subagent # 简单模式,无需协商
45
- else:
46
- mode: team # Full Mode,需要协商
47
-
48
- Team Mode Benefits:
49
- - tech-architect 和 ui-designer 可实时协商
50
- - 解决 API 格式、字段命名等共享决策
51
- - 减少返工率 ~60%
52
-
53
- Script: scripts/team-init.sh detect [skip_tech] [skip_ui]
54
- ```
55
-
56
- ## Entry Gate
57
-
58
- ```yaml
59
- Prerequisites:
60
- 1. REQ_ID 解析:
61
- - 从参数获取
62
- - 或从当前分支推断 (feature/REQ-XXX-*)
63
- - 或从 orchestration_status.json 获取
64
-
65
- 2. BRAINSTORM.md 存在:
66
- - 路径: devflow/requirements/${REQ_ID}/BRAINSTORM.md
67
- - 必须包含: 需求描述、目标用户、核心功能
68
-
69
- 3. Research 完成:
70
- - 路径: devflow/requirements/${REQ_ID}/research/research.md
71
- - 无 TODO/PLACEHOLDER
72
-
73
- 4. Status Check:
74
- - orchestration_status.status ∈ {"initialized", "spec_failed"}
75
-
76
- 5. Constitution Gate:
77
- - 读取 BRAINSTORM.md 验证需求边界
78
- ```
79
-
80
- ## Execution Flow
81
-
82
- ```
83
- ┌─────────────────────────────────────────────────────────────────┐
84
- │ ENTRY GATE │
85
- │ REQ_ID → BRAINSTORM.md → research.md → Status Check │
86
- └─────────────────────────────────────────────────────────────────┘
87
-
88
-
89
- ┌─────────────────────────────────────────────────────────────────┐
90
- │ STAGE 1: PRD Generation │
91
- │ Agent: prd-writer │
92
- │ Output: PRD.md │
93
- │ Rules: ANTI-EXPANSION, INVEST, [NEEDS CLARIFICATION] │
94
- └─────────────────────────────────────────────────────────────────┘
95
-
96
-
97
- ┌─────────────────────────────────────────────────────────────────┐
98
- │ STAGE 2: Parallel Execution │
99
- │ │
100
- │ ┌─────────────────────┐ ┌─────────────────────┐ │
101
- │ │ tech-architect │ │ ui-designer │ │
102
- │ │ (if !--skip-tech) │ │ (if !--skip-ui) │ │
103
- │ │ │ │ │ │
104
- │ │ Output: │ │ Output: │ │
105
- │ │ - TECH_DESIGN.md │ │ - UI_PROTOTYPE.html│ │
106
- │ │ - data-model.md │ │ - ui_design_ │ │
107
- │ │ - contracts/ │ │ strategy.md │ │
108
- │ └─────────────────────┘ └─────────────────────┘ │
109
- │ │
110
- │ Parallel: Both agents run simultaneously via Task tool │
111
- └─────────────────────────────────────────────────────────────────┘
112
-
113
-
114
- ┌─────────────────────────────────────────────────────────────────┐
115
- │ STAGE 3: Epic Generation │
116
- │ Agent: planner │
117
- │ Input: PRD.md + TECH_DESIGN.md (optional) + UI_PROTOTYPE.html │
118
- │ Output: EPIC.md + TASKS.md │
119
- │ Rules: TDD Order, Bite-Sized Tasks, Phase -1 Gates │
120
- └─────────────────────────────────────────────────────────────────┘
121
-
122
-
123
- ┌─────────────────────────────────────────────────────────────────┐
124
- │ EXIT GATE │
125
- │ 1. PRD.md exists, no {{PLACEHOLDER}} │
126
- │ 2. TECH_DESIGN.md exists (if not skipped) │
127
- │ 3. UI_PROTOTYPE.html exists (if not skipped) │
128
- │ 4. EPIC.md exists │
129
- │ 5. TASKS.md exists, TDD order correct │
130
- │ 6. Status: spec_complete │
131
- └─────────────────────────────────────────────────────────────────┘
132
- ```
133
-
134
- ## Stage Details
135
-
136
- ### Stage 1: PRD Generation
137
-
138
- ```yaml
139
- Agent: prd-writer (research-type)
140
- Input:
141
- - BRAINSTORM.md
142
- - research/research.md
143
- - research/internal/codebase-overview.md
144
-
145
- Output:
146
- - PRD.md
147
-
148
- Rules:
149
- - ANTI-EXPANSION: 未提及 → [NEEDS CLARIFICATION]
150
- - NO TECH DETAILS: 只关注 WHAT/WHY
151
- - STORY INDEPENDENCE: 每个故事有独立测试
152
- - PRIORITY MANDATORY: P1, P2, P3...
153
- - MVP IDENTIFICATION: P1 = MVP
154
-
155
- Validation:
156
- - 无 {{PLACEHOLDER}}
157
- - 所有故事有验收标准
158
- - Constitution Check 通过
17
+ /flow:spec "REQ_ID" [--overwrite]
159
18
  ```
160
19
 
161
- ### Stage 2: Parallel Execution
162
-
163
- ```yaml
164
- # =============================================================================
165
- # Team Mode (Full Mode, v4.7)
166
- # =============================================================================
167
- Team Mode:
168
- Condition: !--skip-tech AND !--skip-ui
169
-
170
- Team: spec-design-team
171
- Lead: spec-lead (main agent)
172
- Teammates:
173
- - tech-architect: 技术设计
174
- - ui-designer: UI 原型
175
-
176
- # ---------------------------------------------------------------------------
177
- # Team Mode Execution Steps (详细)
178
- # ---------------------------------------------------------------------------
179
- Execution Steps:
180
-
181
- Step 1 - 初始化 Team:
182
- Action: 调用 scripts/team-init.sh init
183
- Result: 创建 spec-design-team,设置 lead 为当前 agent
184
- State Update: orchestration_status.team.mode = "parallel"
185
-
186
- Step 2 - Spawn Teammates:
187
- Action: 使用 Task tool 并行 spawn 两个 agent
188
- Parallel:
189
- - Task: tech-architect
190
- Agent: flow-tech/references/tech-architect.md
191
- Input: PRD.md, research/codebase-overview.md
192
- Output: TECH_DESIGN.md, data-model.md, contracts/
193
-
194
- - Task: ui-designer
195
- Agent: flow-ui/references/ui-designer.md
196
- Input: PRD.md, STYLE.md (optional)
197
- Output: UI_PROTOTYPE.html, ui_design_strategy.md
198
-
199
- Step 3 - 协商协议 (SendMessage):
200
- Trigger: tech-architect 完成初稿后发起
201
- Protocol: Direct Message via SendMessage tool
202
- Topics:
203
- - api_format: API 响应格式
204
- - field_naming: 数据字段命名
205
- - auth_strategy: 认证策略
206
- - state_management: 前端状态管理
207
- Output: design_decisions.md (协商结果记录)
208
-
209
- Step 4 - 等待完成:
210
- Mechanism: 监听 TeammateIdle 事件
211
- Condition: 两者都完成后进入 Stage 3
212
- Timeout: 30 minutes (可配置)
213
-
214
- Step 5 - 清理 Team:
215
- Action: 发送 shutdown_request 给 teammates
216
- Cleanup: 调用 TeamDelete 清理 Team 状态
217
-
218
- # ---------------------------------------------------------------------------
219
- # SendMessage 协商协议 (v4.7)
220
- # ---------------------------------------------------------------------------
221
- Negotiate Protocol:
222
-
223
- # -------------------------------------------------------------------------
224
- # Topic 1: API Format 协商
225
- # -------------------------------------------------------------------------
226
- api_format:
227
- Initiator: tech-architect
228
- Responder: ui-designer
229
- Decision Owner: tech-architect
230
-
231
- Message Flow:
232
- 1. tech-architect → ui-designer:
233
- SendMessage:
234
- type: "message"
235
- recipient: "ui-designer"
236
- content: |
237
- API 响应格式建议采用 REST + JSON。
238
- - 分页: cursor-based (nextCursor 字段)
239
- - 错误格式: { code, message, details }
240
- - 时间格式: ISO 8601
241
- 请确认是否与前端需求一致。
242
- summary: "API 格式协商请求"
243
-
244
- 2. ui-designer → tech-architect:
245
- SendMessage:
246
- type: "message"
247
- recipient: "tech-architect"
248
- content: |
249
- 确认 REST + JSON 格式。
250
- 建议补充:
251
- - 分页响应包含 hasMore 字段便于前端判断
252
- - 列表接口支持 limit 参数 (默认 20)
253
- summary: "API 格式确认 + 补充建议"
254
-
255
- 3. tech-architect 更新 TECH_DESIGN.md 并记录到 design_decisions.md
256
-
257
- # -------------------------------------------------------------------------
258
- # Topic 2: Field Naming 协商
259
- # -------------------------------------------------------------------------
260
- field_naming:
261
- Initiator: tech-architect
262
- Responder: ui-designer
263
- Decision Owner: tech-architect
264
-
265
- Message Flow:
266
- 1. tech-architect → ui-designer:
267
- SendMessage:
268
- type: "message"
269
- recipient: "ui-designer"
270
- content: |
271
- 数据模型字段命名规范建议:
272
- - API 响应: camelCase (userId, createdAt)
273
- - 数据库: snake_case (user_id, created_at)
274
- - 前端 props: camelCase
275
- 核心实体字段: id, name, status, createdAt, updatedAt
276
- 请确认是否与 UI 组件 props 一致。
277
- summary: "字段命名规范协商"
20
+ ## Execution Steps
278
21
 
279
- 2. ui-designer tech-architect:
280
- SendMessage:
281
- type: "message"
282
- recipient: "tech-architect"
283
- content: |
284
- 确认 camelCase 命名。
285
- UI 组件需要的额外字段:
286
- - displayName (用于展示)
287
- - isActive (布尔状态)
288
- - avatarUrl (头像链接)
289
- summary: "字段命名确认"
22
+ 1. 解析 `REQ_ID` 和可选 `--overwrite`。
23
+ 2. 运行计划生成:
290
24
 
291
- # -------------------------------------------------------------------------
292
- # Topic 3: Auth Strategy 协商
293
- # -------------------------------------------------------------------------
294
- auth_strategy:
295
- Initiator: tech-architect
296
- Responder: ui-designer
297
- Decision Owner: tech-architect
298
-
299
- Message Flow:
300
- 1. tech-architect → ui-designer:
301
- SendMessage:
302
- type: "message"
303
- recipient: "ui-designer"
304
- content: |
305
- 认证策略建议采用 JWT:
306
- - Access Token: 15 分钟过期
307
- - Refresh Token: 7 天过期
308
- - 存储: httpOnly cookie (推荐) 或 localStorage
309
- 前端需要处理 token 刷新逻辑。
310
- summary: "认证策略协商"
311
-
312
- 2. ui-designer → tech-architect:
313
- SendMessage:
314
- type: "message"
315
- recipient: "tech-architect"
316
- content: |
317
- 确认 JWT 方案。
318
- 前端实现:
319
- - 使用 axios interceptor 自动刷新
320
- - 401 响应触发 refresh 流程
321
- - refresh 失败跳转登录页
322
- summary: "认证策略确认"
323
-
324
- # -------------------------------------------------------------------------
325
- # Topic 4: State Management 协商
326
- # -------------------------------------------------------------------------
327
- state_management:
328
- Initiator: ui-designer
329
- Responder: tech-architect
330
- Decision Owner: ui-designer
331
-
332
- Message Flow:
333
- 1. ui-designer → tech-architect:
334
- SendMessage:
335
- type: "message"
336
- recipient: "tech-architect"
337
- content: |
338
- 前端状态管理建议采用 Zustand:
339
- - 全局状态: user, theme, notifications
340
- - 服务端状态: 使用 React Query 管理
341
- - 表单状态: 组件内部 useState
342
- API 缓存策略需要后端支持 ETag 或 Last-Modified。
343
- summary: "状态管理方案协商"
344
-
345
- 2. tech-architect → ui-designer:
346
- SendMessage:
347
- type: "message"
348
- recipient: "ui-designer"
349
- content: |
350
- 确认 Zustand + React Query 方案。
351
- 后端支持:
352
- - 列表接口返回 ETag header
353
- - 详情接口返回 Last-Modified
354
- - 支持 If-None-Match 条件请求
355
- summary: "状态管理确认"
356
-
357
- # ---------------------------------------------------------------------------
358
- # 协商结果记录
359
- # ---------------------------------------------------------------------------
360
- Decision Record:
361
- Path: devflow/requirements/${REQ_ID}/research/design_decisions.md
362
- Format: |
363
- # Design Decisions
364
-
365
- > 由 spec-design-team 协商生成
366
- > 生成时间: ${TIMESTAMP}
367
-
368
- ## API Format
369
- **决策**: REST + JSON, cursor-based pagination
370
- **参与者**: tech-architect, ui-designer
371
- **原因**: 前后端一致性,便于缓存
372
-
373
- ## Field Naming
374
- **决策**: camelCase for API, snake_case for DB
375
- **参与者**: tech-architect, ui-designer
376
- **原因**: 行业标准,前端友好
377
-
378
- ## Auth Strategy
379
- **决策**: JWT with refresh token
380
- **参与者**: tech-architect, ui-designer
381
- **原因**: 无状态,可扩展
382
-
383
- ## State Management
384
- **决策**: Zustand + React Query
385
- **参与者**: ui-designer, tech-architect
386
- **原因**: 轻量级,服务端状态分离
387
-
388
- Negotiate Topics:
389
- - api_format: API 响应格式 (REST/GraphQL)
390
- - field_naming: 数据字段命名规范
391
- - auth_strategy: 认证策略
392
- - state_management: 前端状态管理
393
-
394
- # =============================================================================
395
- # Subagent Mode (Simplified Modes)
396
- # =============================================================================
397
- Subagent Mode:
398
- Condition: --skip-tech OR --skip-ui
399
-
400
- Parallel Agents:
401
- tech-architect:
402
- Condition: !--skip-tech
403
- Input: PRD.md, research/codebase-overview.md
404
- Output: TECH_DESIGN.md, data-model.md, contracts/
405
- Rules:
406
- - ANTI-TECH-CREEP: 复用 baseline 技术栈
407
- - Simplicity Gate: ≤3 栈层
408
- - Integration-First: 契约先定义
409
-
410
- ui-designer:
411
- Condition: !--skip-ui AND PRD 含 UI 关键词
412
- Input: PRD.md, STYLE.md (optional)
413
- Output: UI_PROTOTYPE.html, ui_design_strategy.md
414
- Rules:
415
- - ANTI-GENERIC-DESIGN: 无占位图/AI紫蓝
416
- - 响应式: 3 断点
417
- - 交互完整: 所有状态
418
-
419
- Execution:
420
- - 使用 Task tool 并行调用 agent
421
- - 等待完成后进入 Stage 3
422
- ```
423
-
424
- ### Stage 3: Epic Generation
425
-
426
- ```yaml
427
- Agent: planner (research-type)
428
- Input:
429
- - PRD.md
430
- - TECH_DESIGN.md (if exists)
431
- - UI_PROTOTYPE.html (if exists)
432
-
433
- Output:
434
- - EPIC.md
435
- - TASKS.md
436
-
437
- Rules:
438
- - TDD Order: Phase 2 (Tests) → Phase 3 (Implementation)
439
- - Bite-Sized Tasks: 每个 step 2-5 分钟
440
- - Phase -1 Gates: Simplicity, Anti-Abstraction, Integration-First
441
- - UI Integration: 如有 UI_PROTOTYPE.html,提取组件清单
442
-
443
- Validation:
444
- - EPIC.md 无 {{PLACEHOLDER}}
445
- - TASKS.md TDD 顺序正确
446
- - Constitution Check 通过
447
- ```
448
-
449
- ## Exit Gate
450
-
451
- ```yaml
452
- File Checks:
453
- - [ ] PRD.md exists, no {{PLACEHOLDER}}
454
- - [ ] TECH_DESIGN.md exists (if !--skip-tech)
455
- - [ ] UI_PROTOTYPE.html exists (if !--skip-ui AND UI detected)
456
- - [ ] EPIC.md exists, no {{PLACEHOLDER}}
457
- - [ ] TASKS.md exists, TDD order correct
458
-
459
- Quality Checks:
460
- - [ ] PRD: ANTI-EXPANSION rules passed
461
- - [ ] TECH: ANTI-TECH-CREEP rules passed (if applicable)
462
- - [ ] UI: ANTI-GENERIC-DESIGN rules passed (if applicable)
463
- - [ ] EPIC: Phase -1 Gates passed
464
-
465
- Status Update:
466
- - orchestration_status.status = "spec_complete"
467
- - orchestration_status.phase = "spec"
468
- - orchestration_status.outputs = [list of generated files]
469
- ```
470
-
471
- ## Output Structure
472
-
473
- ```
474
- devflow/requirements/${REQ_ID}/
475
- ├── PRD.md # Always
476
- ├── TECH_DESIGN.md # If !--skip-tech
477
- ├── data-model.md # If !--skip-tech
478
- ├── contracts/ # If !--skip-tech
479
- │ └── openapi.yaml
480
- ├── quickstart.md # If !--skip-tech
481
- ├── UI_PROTOTYPE.html # If !--skip-ui AND UI detected
482
- ├── EPIC.md # Always
483
- ├── TASKS.md # Always
484
- ├── research/
485
- │ ├── research.md # Pre-existing
486
- │ ├── codebase-tech-analysis.md # If !--skip-tech
487
- │ └── ui_design_strategy.md # If !--skip-ui
488
- └── orchestration_status.json # Updated
489
- ```
490
-
491
- ## Error Handling
492
-
493
- ```yaml
494
- Stage 1 Failure (PRD):
495
- - Log error to EXECUTION_LOG.md
496
- - Status: spec_failed
497
- - Retry: /flow-spec --retry
498
-
499
- Stage 2 Failure (Tech/UI):
500
- - If tech-architect fails: Continue with UI, mark tech as skipped
501
- - If ui-designer fails: Continue without UI, mark ui as skipped
502
- - Log partial completion
503
-
504
- Stage 3 Failure (Epic):
505
- - Log error to EXECUTION_LOG.md
506
- - Status: spec_failed
507
- - Retry: /flow-spec --retry --from=epic
25
+ ```bash
26
+ npm run harness:plan -- --change-id "${REQ_ID}" [--overwrite]
508
27
  ```
509
28
 
510
- ## Backward Compatibility
29
+ 3. 校验输出:
30
+ - `devflow/requirements/${REQ_ID}/task-manifest.json`
31
+ - `tasks` 数组非空,`id/dependsOn/run` 字段完整
511
32
 
512
- 旧命令仍可用,但显示 deprecation warning:
33
+ ## Exit Criteria
513
34
 
514
- ```bash
515
- /flow-prd "REQ-123" # ⚠️ Deprecated: Use /flow-spec instead
516
- /flow-tech "REQ-123" # ⚠️ Deprecated: Use /flow-spec instead
517
- /flow-ui "REQ-123" # ⚠️ Deprecated: Use /flow-spec instead
518
- /flow-epic "REQ-123" # ⚠️ Deprecated: Use /flow-spec instead
519
- ```
35
+ - `task-manifest.json` 可通过 schema 校验
36
+ - 任务依赖图无自循环(由 planner 保障)
520
37
 
521
38
  ## Next Step
522
39
 
523
40
  ```bash
524
- /flow-dev "${REQ_ID}"
41
+ /flow:dev "${REQ_ID}"
525
42
  ```
526
-
527
- ## Agent References
528
-
529
- | Agent | Purpose | Location |
530
- |-------|---------|----------|
531
- | prd-writer | PRD 生成 | `flow-prd/references/prd-writer.md` |
532
- | tech-architect | 技术设计 | `flow-tech/references/tech-architect.md` |
533
- | ui-designer | UI 原型 | `flow-ui/references/ui-designer.md` |
534
- | planner | Epic/Tasks | `flow-epic/references/planner.md` |
535
-
536
- ## Constitution Compliance
537
-
538
- - **Article I**: Complete implementation, no placeholders
539
- - **Article II**: Reuse existing components
540
- - **Article III**: No hardcoded secrets
541
- - **Article VI**: TDD order enforced
542
- - **Article VII**: Simplicity Gate
543
- - **Article VIII**: Anti-Abstraction Gate
544
- - **Article IX**: Integration-First Gate
545
- - **Article X**: Requirement boundary enforced
@@ -1,7 +1,5 @@
1
- {"file": "devflow/requirements/{REQ}/BRAINSTORM.md", "reason": "Original intent and requirements"}
2
- {"file": "devflow/requirements/{REQ}/research/research.md", "reason": "Research findings"}
3
- {"file": "devflow/requirements/{REQ}/research/internal/codebase-overview.md", "reason": "Codebase analysis", "optional": true}
4
- {"file": "devflow/spec/frontend/index.md", "reason": "Frontend conventions", "optional": true}
5
- {"file": "devflow/spec/backend/index.md", "reason": "Backend conventions", "optional": true}
6
- {"file": "devflow/STYLE.md", "reason": "Design style guide", "optional": true}
7
- {"file": "CLAUDE.md", "reason": "Tech stack baseline"}
1
+ {"file": "devflow/requirements/{REQ}/context-package.md", "reason": "Execution context package"}
2
+ {"file": "devflow/requirements/{REQ}/TASKS.md", "reason": "Task source", "optional": true}
3
+ {"file": "devflow/requirements/{REQ}/task-manifest.json", "reason": "Previous manifest", "optional": true}
4
+ {"file": "devflow/requirements/{REQ}/harness-state.json", "reason": "Lifecycle status", "optional": true}
5
+ {"file": ".claude/rules/project-constitution.md", "reason": "Quality rules and constraints"}