@peterxiaoyang/superspec 0.1.55 → 0.1.57
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/README.md +28 -32
- package/dist/approved_ref.d.ts +26 -0
- package/dist/approved_ref.js +159 -0
- package/dist/cli.js +2 -0
- package/dist/code_review.d.ts +7 -0
- package/dist/code_review.js +92 -1
- package/dist/format.d.ts +25 -1
- package/dist/format.js +235 -1
- package/dist/next.js +4 -1
- package/dist/phase_confirmation.js +7 -2
- package/dist/phase_plan.d.ts +6 -1
- package/dist/phase_plan.js +172 -44
- package/dist/propose_round.d.ts +7 -1
- package/dist/propose_round.js +35 -0
- package/dist/record.js +27 -7
- package/dist/transition.js +22 -7
- package/dist/types.d.ts +28 -1
- package/dist/workflow_config.d.ts +15 -0
- package/dist/workflow_config.js +47 -0
- package/package.json +1 -1
- package/templates/workflow/AGENTS.md +2 -0
- package/templates/workflow/agents-md/code-reviewer.md +1 -1
- package/templates/workflow/agents-md/critic.md +1 -1
- package/templates/workflow/prompts/architect.md +1 -0
- package/templates/workflow/prompts/code-reviewer.md +4 -4
- package/templates/workflow/prompts/critic.md +3 -1
- package/templates/workflow/prompts/executor.md +2 -0
- package/templates/workflow/prompts/explore.md +1 -1
- package/templates/workflow/skills/superspec-explore/SKILL.md +16 -12
- package/templates/workflow/skills/superspec-propose/SKILL.md +27 -4
|
@@ -14,6 +14,8 @@ metadata:
|
|
|
14
14
|
|
|
15
15
|
先运行 `superspec transition next --change "<change>"`，以返回的事项、材料目标、确认、审查与后续动作作为唯一流程依据；不要根据 Skill 模板猜测产物目录或推进方式。只把用户已确认的行为、边界和有证据的风险写成计划，不改业务代码。
|
|
16
16
|
|
|
17
|
+
计划分两拍。第一拍先形成 `proposal.md`、`specs/` 与 `design.md`（含结构变更清单和待用户确认的 DEC），然后运行 `next` 让用户逐个决定结构取舍；所有 DEC 关闭后才写 `tasks.md` 与 `test-contract.md`。结构决定改变方案时，任务与测试契约按新方案编写，不在旧方案的任务上修补。用户在任务写出来之前看到并决定"这次要动哪些结构"，是这一阶段最重要的产出。
|
|
18
|
+
|
|
17
19
|
需求源、业务口径或验收更新时，先在 `proposal.md` 增加 `## 需求变化`，记录变化来源、变化、受影响能力、已修改材料、保持不变的范围和处理方式；再按实际影响同步规格、设计和测试契约。
|
|
18
20
|
|
|
19
21
|
人类可读正文使用简体中文。源码锚点采用能唯一定位的最短写法；文档引用使用 `文件#锚点`，让实现者能打开原材料。
|
|
@@ -114,6 +116,12 @@ metadata:
|
|
|
114
116
|
<!-- 可选：本方案存在真实可行且容易误走的替代路线时保留 -->
|
|
115
117
|
**不采用：** <替代路线> — <不采用原因>
|
|
116
118
|
|
|
119
|
+
## 结构变更清单
|
|
120
|
+
|
|
121
|
+
| ID | 类别 | 变更 | 需求依据 | 决定 |
|
|
122
|
+
|---|---|---|---|---|
|
|
123
|
+
| SC-001 | <类别> | <新增或改变的结构，写到表/列/类/方法级> | <specs/<cap>/spec.md#Requirement: <标题> 或 TEST-xxx> | <DEC-xxx 或 —> |
|
|
124
|
+
|
|
117
125
|
<!-- 可选：同一取舍横跨多个功能点时保留，否则优先写在对应方案内 -->
|
|
118
126
|
## 整体方案取舍
|
|
119
127
|
| 方案 | 收益 | 代价 | 结论 |
|
|
@@ -122,7 +130,7 @@ metadata:
|
|
|
122
130
|
|
|
123
131
|
<!-- 可选：存在必须由使用者承担结果的高影响设计取舍时保留；确认后回写最终方案 -->
|
|
124
132
|
## 待用户确认
|
|
125
|
-
- [ ] DEC-001
|
|
133
|
+
- [ ] DEC-001 <决定、候选结果、推荐与依据、对交付的影响；列出它会带来的 SC 条目>
|
|
126
134
|
|
|
127
135
|
<!-- 可选：同一契约被多个功能点共享时保留，局部契约写在对应方案内 -->
|
|
128
136
|
## 关键契约
|
|
@@ -138,9 +146,24 @@ metadata:
|
|
|
138
146
|
|
|
139
147
|
```
|
|
140
148
|
|
|
149
|
+
`## 结构变更清单` 是本次已批准结构的边界，工作流会解析它、在开始实现前展示给用户，并作为代码审查判断"是否多做"的依据。没有结构变更时在该标题下写 `无`。类别固定为：
|
|
150
|
+
|
|
151
|
+
| 类别 | 覆盖 | 决定列 |
|
|
152
|
+
|---|---|---|
|
|
153
|
+
| 新增持久化结构 | 新表、新列、新实体/DAO、新索引、分表模板 | 必须引用 DEC |
|
|
154
|
+
| 迁移或回填 | 结构脚本之外的数据迁移、回填、双写 | 必须引用 DEC |
|
|
155
|
+
| 功能开关 | 任何运行时开关或灰度控制 | 必须引用 DEC |
|
|
156
|
+
| 新增公共接口 | HTTP/RPC 入口、消息主题、跨服务或跨仓库契约 | 必须引用 DEC |
|
|
157
|
+
| 删除既有路径 | 删除兼容读取/写入/回退路径、删除既有公共方法 | 必须引用 DEC |
|
|
158
|
+
| 改既有公共签名 | 既有公共/受保护方法的参数或返回类型变化 | 必须引用 DEC |
|
|
159
|
+
| 改变既有数据语义 | 既有字段含义、归属或默认值变化 | 必须引用 DEC |
|
|
160
|
+
| 新增公共类型 | VO / DTO / 枚举 / 工具类 | 可写 `—` |
|
|
161
|
+
|
|
162
|
+
需决定类别的"需求依据"只能是 specs 的 Requirement 或 TEST；找不到这样的依据，说明该结构不是需求要求的，不要写进清单，也不要写进方案。一个 DEC 可以覆盖同一决定带来的多条 SC。`proposal.md#Impact` 不能作为任何条目的依据。
|
|
163
|
+
|
|
141
164
|
### tasks.md
|
|
142
165
|
|
|
143
|
-
使用 OpenSpec 的任务分组；每个顶格 checkbox 是一个可独立完成和验证的 task
|
|
166
|
+
使用 OpenSpec 的任务分组；每个顶格 checkbox 是一个可独立完成和验证的 task。任务按用户或调用方可观察的行为切分，为该行为服务的跨层机械改动归入同一 task，不按技术层单列；只有多个独立行为或入口不能共享一个验证边界时才拆开。审计、对账、撤销之类没有可观察交付的工作不是 task。
|
|
144
167
|
|
|
145
168
|
```markdown
|
|
146
169
|
# Tasks
|
|
@@ -166,11 +189,11 @@ metadata:
|
|
|
166
189
|
- 边界: <不改业务行为>
|
|
167
190
|
```
|
|
168
191
|
|
|
169
|
-
|
|
192
|
+
`验收` 与 `边界` 必须能针对该 task 对照实现，不写可套用到任何 task 的空话；引用必须能定位到真正支持该 task 的材料。行为 task 的测试引用相应场景；纯非行为 task 才可留空并在验收/边界说明原因。`交付` 和 `依赖` 用于开始实现前的阅读摘要：只写真实前置交付，不能把纯排列顺序写成依赖。验证要求由工作流决定，计划不预设执行步骤。
|
|
170
193
|
|
|
171
194
|
### test-contract.md
|
|
172
195
|
|
|
173
|
-
|
|
196
|
+
把每个需自动验证的验收行为写成能推导断言的场景，不写测试命令或断言代码。场景描述调用方可观察的结果，不把内部实现过程写成验收。通常一个场景描述一个可观察行为；名称写“调用方得到什么”，不写“某模块调用了什么”。一个 change 用少量场景覆盖主要行为与直接边界即可，不为每个任务、每一层或每个消费者各写一个场景。
|
|
174
197
|
|
|
175
198
|
```markdown
|
|
176
199
|
# Test Contract
|