@peterxiaoyang/superspec 0.1.14 → 0.1.16-alpha
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 +37 -36
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +301 -0
- package/dist/format.d.ts +29 -0
- package/dist/format.js +141 -0
- package/dist/install.d.ts +18 -0
- package/dist/install.js +161 -0
- package/dist/next.d.ts +3 -0
- package/dist/next.js +161 -0
- package/dist/openspec.d.ts +9 -0
- package/dist/openspec.js +41 -0
- package/dist/record.d.ts +20 -0
- package/dist/record.js +266 -0
- package/dist/skill_loop.d.ts +23 -0
- package/dist/skill_loop.js +58 -0
- package/dist/store.d.ts +31 -0
- package/dist/store.js +213 -0
- package/dist/sync.d.ts +3 -0
- package/dist/sync.js +135 -0
- package/dist/task.d.ts +7 -0
- package/dist/task.js +44 -0
- package/dist/transition.d.ts +34 -0
- package/dist/transition.js +400 -0
- package/dist/types.d.ts +141 -0
- package/dist/types.js +3 -0
- package/package.json +8 -53
- package/templates/workflow/agents/architect.toml +13 -0
- package/{adapters/codex → templates/workflow}/agents/code-reviewer.toml +2 -2
- package/templates/workflow/agents/critic.toml +13 -0
- package/{adapters/codex → templates/workflow}/agents/executor.toml +2 -2
- package/{adapters/codex → templates/workflow}/agents/explore.toml +3 -3
- package/templates/workflow/agents/final-audit.toml +13 -0
- package/templates/workflow/agents/proposal-auditor.toml +13 -0
- package/{adapters/codex → templates/workflow}/agents/test-engineer.toml +4 -4
- package/{adapters/codex → templates/workflow}/agents/test-runner.toml +2 -2
- package/{adapters/codex → templates/workflow}/agents/verifier.toml +2 -2
- package/templates/workflow/prompts/architect.md +16 -0
- package/templates/workflow/prompts/critic.md +16 -0
- package/templates/workflow/prompts/explore.md +1 -1
- package/templates/workflow/prompts/final-audit.md +32 -0
- package/templates/workflow/prompts/proposal-auditor.md +34 -0
- package/templates/workflow/prompts/test-engineer.md +16 -0
- package/templates/workflow/skills/superspec-apply/SKILL.md +39 -121
- package/templates/workflow/skills/superspec-archive/SKILL.md +17 -49
- package/templates/workflow/skills/superspec-explore/SKILL.md +34 -70
- package/templates/workflow/skills/superspec-propose/SKILL.md +57 -60
- package/templates/workflow/skills/superspec-review/SKILL.md +18 -85
- package/adapters/codex/agents/architect.toml +0 -13
- package/adapters/codex/agents/critic.toml +0 -13
- package/adapters/codex/install-map.json +0 -116
- package/bin/launch.js +0 -37
- package/bin/superspec-check.js +0 -4
- package/bin/superspec-hook.js +0 -4
- package/bin/superspec-init.js +0 -4
- package/bin/superspec.js +0 -4
- package/dist/src/apply_worker_chain.d.ts +0 -60
- package/dist/src/apply_worker_chain.js +0 -1283
- package/dist/src/apply_worker_chain_lifecycle.d.ts +0 -21
- package/dist/src/apply_worker_chain_lifecycle.js +0 -409
- package/dist/src/archive.d.ts +0 -23
- package/dist/src/archive.js +0 -430
- package/dist/src/cli.d.ts +0 -1
- package/dist/src/cli.js +0 -33
- package/dist/src/cli_args.d.ts +0 -32
- package/dist/src/cli_args.js +0 -454
- package/dist/src/core.d.ts +0 -20
- package/dist/src/core.js +0 -394
- package/dist/src/disclosure.d.ts +0 -35
- package/dist/src/disclosure.js +0 -671
- package/dist/src/doctor.d.ts +0 -44
- package/dist/src/doctor.js +0 -230
- package/dist/src/evidence.d.ts +0 -29
- package/dist/src/evidence.js +0 -1107
- package/dist/src/gates.d.ts +0 -19
- package/dist/src/gates.js +0 -1631
- package/dist/src/git.d.ts +0 -8
- package/dist/src/git.js +0 -112
- package/dist/src/hooks/adapter.d.ts +0 -5
- package/dist/src/hooks/adapter.js +0 -347
- package/dist/src/hooks/guard_api.d.ts +0 -12
- package/dist/src/hooks/guard_api.js +0 -797
- package/dist/src/hooks/health.d.ts +0 -4
- package/dist/src/hooks/health.js +0 -86
- package/dist/src/hooks/policy_event.d.ts +0 -41
- package/dist/src/hooks/policy_event.js +0 -2634
- package/dist/src/hooks/types.d.ts +0 -72
- package/dist/src/hooks/types.js +0 -1
- package/dist/src/hooks/validation.d.ts +0 -3
- package/dist/src/hooks/validation.js +0 -70
- package/dist/src/i18n.d.ts +0 -21
- package/dist/src/i18n.js +0 -720
- package/dist/src/init_cli.d.ts +0 -28
- package/dist/src/init_cli.js +0 -404
- package/dist/src/install_engine.d.ts +0 -71
- package/dist/src/install_engine.js +0 -538
- package/dist/src/invariants.d.ts +0 -16
- package/dist/src/invariants.js +0 -363
- package/dist/src/openspec.d.ts +0 -37
- package/dist/src/openspec.js +0 -274
- package/dist/src/packet_render.d.ts +0 -5
- package/dist/src/packet_render.js +0 -1767
- package/dist/src/packet_schema.d.ts +0 -59
- package/dist/src/packet_schema.js +0 -1
- package/dist/src/paths.d.ts +0 -22
- package/dist/src/paths.js +0 -203
- package/dist/src/project_init.d.ts +0 -33
- package/dist/src/project_init.js +0 -191
- package/dist/src/self_update.d.ts +0 -14
- package/dist/src/self_update.js +0 -56
- package/dist/src/state.d.ts +0 -37
- package/dist/src/state.js +0 -464
- package/dist/src/tasks.d.ts +0 -38
- package/dist/src/tasks.js +0 -373
- package/dist/src/util.d.ts +0 -163
- package/dist/src/util.js +0 -792
- package/dist/superspec.d.ts +0 -6
- package/dist/superspec.js +0 -97
- package/dist/superspec_guard.d.ts +0 -4
- package/dist/superspec_guard.js +0 -19
- package/dist/superspec_hook.d.ts +0 -4
- package/dist/superspec_hook.js +0 -35
- package/dist/superspec_init.d.ts +0 -2
- package/dist/superspec_init.js +0 -17
- package/schemas/hook-event.schema.json +0 -27
- package/schemas/install-manifest.schema.json +0 -97
- package/templates/hooks/codex-hooks.json +0 -35
- package/templates/sidecar/archive-preservation.json +0 -11
- package/templates/sidecar/business-invariants.md +0 -38
- package/templates/sidecar/config.yaml +0 -13
- package/templates/sidecar/discovery.md +0 -33
- package/templates/sidecar/test-contract.md +0 -27
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superspec-explore
|
|
3
|
-
description: "
|
|
3
|
+
description: "探索现状、澄清范围、维护 discovery.md;通过 transition/record 把 change 从 init 推进到 propose。"
|
|
4
4
|
metadata:
|
|
5
5
|
author: SuperSpec
|
|
6
6
|
source: SuperSpec
|
|
@@ -8,90 +8,54 @@ metadata:
|
|
|
8
8
|
|
|
9
9
|
# SuperSpec Explore
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
你是探索阶段。职责:调查现状、梳理范围、识别风险,把结果沉淀到 `discovery.md`。不写业务代码,不提前写 proposal/specs/design/tasks。
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- 用户可见文案不得使用“裁决”描述用户动作;统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
|
|
15
|
-
- 不把内部证据种类、reason code、JSON 字段大全直接转述给用户;需要诊断时才引用原文。
|
|
16
|
-
- 普通 workflow 命令使用 `--format agent`;`--format json` 只用于诊断,不作为默认上下文。
|
|
13
|
+
## 驱动方式
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
所有状态由 transition engine 管理。循环:
|
|
19
16
|
|
|
20
|
-
|
|
21
|
-
|
|
17
|
+
1. `superspec transition next --change "<change>" --risk strict` 获取下一步
|
|
18
|
+
2. 执行返回的命令
|
|
19
|
+
3. 登记结果
|
|
20
|
+
4. 回到 1
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向用户提问,收到回答后 `superspec record user-decision --change "<change>" --input <FILE>`。
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
本技能默认以 `risk=strict` 驱动。探索完成后,`explore→propose` 会先创建 `critic` 工作项,由 Critic 审查需求澄清记录。该工作项必须产出 `job_report_json`,并通过 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 登记。
|
|
26
25
|
|
|
27
|
-
##
|
|
26
|
+
## 本阶段做什么
|
|
28
27
|
|
|
29
|
-
|
|
30
|
-
|
|
28
|
+
1. **建立事实基线**:读代码、查架构、理解当前系统行为(只读)
|
|
29
|
+
2. **写 discovery.md**:
|
|
30
|
+
3. **澄清歧义**:有阻塞歧义时向用户提问
|
|
31
31
|
|
|
32
|
-
##
|
|
32
|
+
## discovery.md 格式
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
superspec init --scope project --format agent
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
随后用 `openspec list --json` 查找匹配 change;若已有则复用,若没有则直接创建,不要先跑 `openspec --help` / `openspec change --help` / `openspec new --help` 探测语法(命令失败或版本报错时才查 help 诊断)。
|
|
39
|
-
|
|
40
|
-
```text
|
|
41
|
-
openspec list --json
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
仅当 `openspec list --json` 没有匹配 change 时运行:
|
|
45
|
-
|
|
46
|
-
```text
|
|
47
|
-
openspec new change "<change>" --description "<用户需求摘要>"
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
然后读取当前上下文:
|
|
51
|
-
|
|
52
|
-
```text
|
|
53
|
-
openspec status --change "<change>" --json
|
|
54
|
-
superspec check check-init --change "<change>" --format agent
|
|
55
|
-
superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
遇到 `block` 就停止,按检查结果的下一步提示处理;不要绕过检查。
|
|
59
|
-
|
|
60
|
-
## OpenSpec 边界
|
|
34
|
+
写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`:
|
|
61
35
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
- OpenSpec 负责 change 结构和后续 artifact 语义;本阶段只补 SuperSpec discovery 证据。
|
|
65
|
-
- 如果发现需要正式方案、规格、设计或任务,先写入 discovery,再交给 `superspec-propose`。
|
|
66
|
-
- 代码事实扫描可由主线程直接完成;若并行创建只读子代理,使用 repo-local `.codex/agents/explore.toml`。该角色只辅助 discovery 覆盖,不能替代 `critic` 审查证据。
|
|
36
|
+
```markdown
|
|
37
|
+
# Discovery
|
|
67
38
|
|
|
68
|
-
##
|
|
39
|
+
## 现状
|
|
40
|
+
(当前系统怎么工作)
|
|
69
41
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
```text
|
|
73
|
-
superspec check review-packet --change "<change>" --gate explore_complete --role critic --round 1 --format prompt
|
|
74
|
-
```
|
|
42
|
+
## 需要改什么
|
|
43
|
+
(要实现的需求)
|
|
75
44
|
|
|
76
|
-
|
|
45
|
+
## 风险和边界
|
|
46
|
+
(技术风险、依赖、兼容性)
|
|
77
47
|
|
|
78
|
-
|
|
79
|
-
|
|
48
|
+
## 待确认问题
|
|
49
|
+
- [ ] 问题1的描述
|
|
50
|
+
- [ ] 问题2的描述
|
|
80
51
|
```
|
|
81
52
|
|
|
82
|
-
|
|
53
|
+
**重要**:`- [ ]` 标记的待确认问题必须全部解决(用户确认后改为 `- [x]` 或删除),否则 transition engine 会阻止推进到 propose。
|
|
83
54
|
|
|
84
|
-
##
|
|
85
|
-
|
|
86
|
-
- 关键范围、非目标、验收标准、业务语义或设计边界问题必须面向用户说明并等待明确确认。
|
|
87
|
-
- 探索结论、范围边界和进入 propose 的授权必须等待用户确认后再记录 evidence。
|
|
88
|
-
- discovery.md 必须含 `## 待确认问题` 段(标题含「确认」字样即可,如「待确认问题」「需要用户确认的问题」)。每条问题用 `- [ ]`(未决)或 `- [x]`(已确认)标记;也可在已确认项写「已确认:」。**该段只要还有 `- [ ]` 或「仍需确认/待确认」项,`explore_complete` 检查就不会通过**,不得记录人工确认,也不得进入 propose。
|
|
89
|
-
- 用户看到的文字要用中文业务语言;内部 JSON 名只写进证据、命令输出或诊断片段。
|
|
90
|
-
|
|
91
|
-
## 完成检查
|
|
92
|
-
|
|
93
|
-
```text
|
|
94
|
-
superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
|
|
95
|
-
```
|
|
55
|
+
## Guardrails
|
|
96
56
|
|
|
97
|
-
|
|
57
|
+
- 不改业务代码
|
|
58
|
+
- 不写 proposal/specs/design/tasks
|
|
59
|
+
- 不跳过 transition 直接编辑状态文件
|
|
60
|
+
- 用户未确认的决策不自行推断
|
|
61
|
+
- strict 模式下不跳过 `critic`
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superspec-propose
|
|
3
|
-
description: "
|
|
3
|
+
description: "编写计划文档(proposal/specs/design/tasks + 不变量 + 测试契约);通过 transition 推进到 propose_ready。"
|
|
4
4
|
metadata:
|
|
5
5
|
author: SuperSpec
|
|
6
6
|
source: SuperSpec
|
|
@@ -8,87 +8,84 @@ metadata:
|
|
|
8
8
|
|
|
9
9
|
# SuperSpec Propose
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
你是计划阶段。职责:把探索结论转化为可执行的计划——写 proposal.md / specs / design.md / tasks.md + business-invariants.md + test-contract.md。
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- 用户可见文案不得使用“裁决”描述用户动作;统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
|
|
15
|
-
- 不把内部证据种类、reason code、JSON 字段大全直接转述给用户;需要诊断时才引用原文。
|
|
16
|
-
- 普通 workflow 命令使用 `--format agent`;`--format json` 只用于诊断,不作为默认上下文。
|
|
13
|
+
## 驱动方式
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
所有状态由 transition engine 管理。循环:
|
|
19
16
|
|
|
20
|
-
|
|
21
|
-
|
|
17
|
+
1. `superspec transition next --change "<change>" --risk strict` 获取下一步
|
|
18
|
+
2. 执行返回的命令
|
|
19
|
+
3. 登记结果
|
|
20
|
+
4. 回到 1
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
next 返回 `required_job` 说明需要审查工作项——跑 `superspec jobs packet` 拿到工作说明,执行审查,`superspec record job-submit --change "<change>" --job <JOB> --report <FILE>`。
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
本技能默认以 `risk=strict` 驱动。计划阶段进入 `propose-ready` 前必须完成这些审核工作项:
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
- `proposal-auditor`
|
|
27
|
+
- `critic`
|
|
28
|
+
- `architect`
|
|
29
|
+
- `test-engineer`
|
|
28
30
|
|
|
29
|
-
|
|
30
|
-
superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
遇到 `block` 就停止,回 explore 阶段补事实或确认。
|
|
31
|
+
所有工作项报告都必须按 packet 的 `job_report_json` 契约提交。
|
|
34
32
|
|
|
35
|
-
##
|
|
33
|
+
## 本阶段做什么
|
|
36
34
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- OpenSpec 标准文件必须通过 `openspec instructions` 生成,不要手写绕过:
|
|
35
|
+
### proposal.md
|
|
36
|
+
需求陈述、方案概述、影响范围。
|
|
40
37
|
|
|
41
|
-
|
|
42
|
-
openspec instructions
|
|
43
|
-
```
|
|
38
|
+
### specs/
|
|
39
|
+
OpenSpec 能力规范增量(`openspec instructions specs` 格式)。
|
|
44
40
|
|
|
45
|
-
|
|
41
|
+
### design.md
|
|
42
|
+
技术方案、关键决策、替代方案。
|
|
46
43
|
|
|
47
|
-
|
|
44
|
+
### tasks.md
|
|
45
|
+
任务列表,格式:
|
|
48
46
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
3. 先读 dependencies 列出的已完成 artifact,再按 template 写到 `resolvedOutputPath`;context/rules 是对作者的约束,不写进产出文件。
|
|
52
|
-
4. 辅助文档(`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`)如果尚不存在,就按 SuperSpec 内置模板在 change 内 `.superspec/artifacts/` 新建;已存在则基于当前阶段要求更新。
|
|
53
|
-
5. `invariants_reviewed` 的 `workflow-packet` 会下发 `business_invariants_template` 与 `business_invariants_rules`;必须按该骨架直接填写,不得改成段落/列表。
|
|
54
|
-
6. `test_contract_drafted` 的 `workflow-packet` 会下发 `test_contract_template` 与 `test_contract_rules`;必须按该骨架直接填写,不得改成段落/列表。
|
|
55
|
-
7. `business-invariants.md` 的 `## Invariants` / `## Mapping` 和 `test-contract.md` 的 `## 测试覆盖矩阵` 必须保持 Markdown 表格,列名原样保留。
|
|
47
|
+
```markdown
|
|
48
|
+
# Tasks
|
|
56
49
|
|
|
57
|
-
|
|
50
|
+
- [ ] TASK-001 实现登录功能 tdd_required:true
|
|
51
|
+
- [ ] TASK-002 更新文档 tdd_required:false no_tdd_reason:documentation-only
|
|
52
|
+
- [ ] TASK-003 配置变更 tdd_required:false no_tdd_reason:configuration-only
|
|
53
|
+
```
|
|
58
54
|
|
|
59
|
-
|
|
55
|
+
规则:
|
|
56
|
+
- `tdd_required:true`(默认)——改运行时代码/业务逻辑/数据迁移/权限/外部接口
|
|
57
|
+
- `tdd_required:false` + `no_tdd_reason:xxx`——纯文档/配置/机械改名/生成物
|
|
60
58
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
superspec check workflow-packet --change "<change>" --gate design_complete --format agent
|
|
64
|
-
superspec check workflow-packet --change "<change>" --gate invariants_reviewed --format agent
|
|
65
|
-
superspec check workflow-packet --change "<change>" --gate test_contract_drafted --format agent
|
|
66
|
-
superspec check workflow-packet --change "<change>" --gate test_contract_honored --format agent
|
|
67
|
-
superspec check workflow-packet --change "<change>" --gate tasks_complete --format agent
|
|
68
|
-
superspec check workflow-packet --change "<change>" --gate propose_complete --format agent
|
|
69
|
-
superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
|
|
70
|
-
```
|
|
59
|
+
### business-invariants.md
|
|
60
|
+
格式:
|
|
71
61
|
|
|
72
|
-
|
|
62
|
+
```markdown
|
|
63
|
+
# Business Invariants
|
|
73
64
|
|
|
74
|
-
|
|
65
|
+
- INV-001 用户密码必须加密存储
|
|
66
|
+
- INV-002 订单金额不能为负数
|
|
67
|
+
```
|
|
75
68
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
- business-invariants 和 test-contract review 使用 repo-local `critic` / `test-engineer`。
|
|
79
|
-
- reviewer prompt 一律由 `review-packet --format prompt` 生成;主线程 digest 输入一律由 `review-packet --role main-thread --format agent` 读取。
|
|
80
|
-
- 第二轮及以后的审查,必须由检查命令把上一轮的问题注入提示,不手写历史 finding 清单。
|
|
69
|
+
### test-contract.md
|
|
70
|
+
格式:
|
|
81
71
|
|
|
82
|
-
|
|
72
|
+
```markdown
|
|
73
|
+
# Test Contract
|
|
83
74
|
|
|
84
|
-
|
|
75
|
+
| test_id | invariant | scenario |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| TEST-001 | INV-001 | 注册时密码被加密 |
|
|
78
|
+
| TEST-002 | INV-002 | 订单金额为负时拒绝 |
|
|
79
|
+
```
|
|
85
80
|
|
|
86
|
-
|
|
81
|
+
## 完成条件
|
|
87
82
|
|
|
88
|
-
|
|
83
|
+
tasks.md 作为计划文档就绪(不是复选框全完成)+ 基础职责文档齐全 → next 返回 propose-ready 命令。
|
|
89
84
|
|
|
90
|
-
|
|
91
|
-
superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
|
|
92
|
-
```
|
|
85
|
+
## Guardrails
|
|
93
86
|
|
|
94
|
-
|
|
87
|
+
- tasks.md 只列任务,不实现
|
|
88
|
+
- 不改业务代码
|
|
89
|
+
- tdd_required 标注真实
|
|
90
|
+
- 不跳过 transition
|
|
91
|
+
- 不跳过 strict 模式下的审核工作项
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superspec-review
|
|
3
|
-
description: "
|
|
3
|
+
description: "执行最终审查,处理 final-audit 工作项,推进到 accept。"
|
|
4
4
|
metadata:
|
|
5
5
|
author: SuperSpec
|
|
6
6
|
source: SuperSpec
|
|
@@ -8,95 +8,28 @@ metadata:
|
|
|
8
8
|
|
|
9
9
|
# SuperSpec Review
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
你是审查阶段。职责:最终审查——验证实现质量、处理最终审查工作项、推进到 accept。
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- 用户可见文案不得使用“裁决”描述用户动作;统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
|
|
15
|
-
- 不把内部证据种类、reason code、JSON 字段大全直接转述给用户;需要诊断时才引用原文。
|
|
16
|
-
- 普通 workflow 命令使用 `--format agent`;`--format json` 只用于诊断,不作为默认上下文。
|
|
13
|
+
## 驱动方式
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
所有状态由 transition engine 管理。循环:
|
|
19
16
|
|
|
20
|
-
|
|
21
|
-
|
|
17
|
+
1. `superspec transition next --change "<change>"` 获取下一步
|
|
18
|
+
2. 执行返回的命令
|
|
19
|
+
3. 登记结果
|
|
20
|
+
4. 回到 1
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
next 返回 `required_job` 说明需要 final-audit——跑 `superspec jobs packet` 拿工作说明,执行审查,`superspec record job-submit --change "<change>" --job <JOB> --report <FILE>`。
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
## 本阶段做什么
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
1. **确认所有任务完成**:review-ready 会检查 tasks.md 无未完成项
|
|
27
|
+
2. **处理 final-audit**:审查 proposal + 实现 + 测试契约一致性
|
|
28
|
+
3. **accept**:`superspec transition accept --change "<change>"`
|
|
28
29
|
|
|
29
|
-
|
|
30
|
-
superspec check check-init --change "<change>" --format agent
|
|
31
|
-
```
|
|
30
|
+
## Guardrails
|
|
32
31
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
遇到任何返回状态为 `block` 就停止。review 不直接回改 `tasks.md` checkbox。
|
|
40
|
-
|
|
41
|
-
## 专用代理边界
|
|
42
|
-
|
|
43
|
-
Review 必须使用本仓库安装的 repo-local native agents(专用代理),不要调用全局 `$code-review`、OMX workflow、主线程自审或普通 markdown 报告替代。
|
|
44
|
-
|
|
45
|
-
必需入口:
|
|
46
|
-
|
|
47
|
-
- `.codex/agents/code-reviewer.toml` / `.codex/prompts/code-reviewer.md`
|
|
48
|
-
- `.codex/agents/architect.toml` / `.codex/prompts/architect.md`
|
|
49
|
-
- `.codex/agents/critic.toml` / `.codex/prompts/critic.md`
|
|
50
|
-
- `.codex/agents/verifier.toml` / `.codex/prompts/verifier.md`
|
|
51
|
-
|
|
52
|
-
每个审查提示都先由检查命令产出:
|
|
53
|
-
|
|
54
|
-
```text
|
|
55
|
-
superspec check review-packet --change "<change>" --gate review_complete --role code-reviewer --round 1 --format prompt
|
|
56
|
-
superspec check review-packet --change "<change>" --gate review_complete --role architect --round 1 --format prompt
|
|
57
|
-
superspec check review-packet --change "<change>" --gate review_complete --role critic --round 1 --format prompt
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
## Final Verification 边界
|
|
61
|
-
|
|
62
|
-
只在 allow 评估路径运行 final verification:
|
|
63
|
-
|
|
64
|
-
```text
|
|
65
|
-
openspec validate "<change>"
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
然后执行 test contract 要求的最终测试,启动本仓库 `verifier` 和 `critic` 做验证审查。验证提示也必须由检查命令产出:
|
|
69
|
-
|
|
70
|
-
```text
|
|
71
|
-
superspec check review-packet --change "<change>" --gate review_complete --role verifier --round 1 --format prompt
|
|
72
|
-
superspec check review-packet --change "<change>" --gate review_complete --role critic --round 1 --kind verification_review --format prompt
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
verification 只提供 proof/gap,不替代主流程最终判断。
|
|
76
|
-
|
|
77
|
-
## 主线程最终判断边界
|
|
78
|
-
|
|
79
|
-
主线程写最终判断前读取:
|
|
80
|
-
|
|
81
|
-
```text
|
|
82
|
-
superspec check review-packet --change "<change>" --gate review_complete --role main-thread --round 1 --format agent
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
`review_complete` 是只允许通过的阶段检查。通过路径由主线程写本轮审查结论(主线程直接写,不携带代理字段)。
|
|
86
|
-
|
|
87
|
-
`request_changes` 不是 review_complete allow。它必须写清 `request_changes_route`:
|
|
88
|
-
|
|
89
|
-
- `reopen_tasks`:回 `superspec-apply` 修复既有 task。
|
|
90
|
-
- `change_update`:回 propose/change update。
|
|
91
|
-
|
|
92
|
-
request-changes round 不生成 allow-path verification,也不调用 `check-review-complete`。
|
|
93
|
-
|
|
94
|
-
## 完成检查
|
|
95
|
-
|
|
96
|
-
仅 allow path 运行:
|
|
97
|
-
|
|
98
|
-
```text
|
|
99
|
-
superspec check workflow-packet --change "<change>" --gate review_complete --format agent
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
只有检查结果显示通过后,才进入 `superspec-archive`。
|
|
32
|
+
- 不改业务代码(审查阶段只读)
|
|
33
|
+
- 不跳过 final-audit 直接 accept
|
|
34
|
+
- 审查报告必须真实引用文件内容,不编造
|
|
35
|
+
- 不跳过 transition
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
# oh-my-codex agent: architect
|
|
2
|
-
name = "architect"
|
|
3
|
-
description = "System design, boundaries, interfaces, long-horizon tradeoffs"
|
|
4
|
-
model_reasoning_effort = "xhigh"
|
|
5
|
-
developer_instructions = """
|
|
6
|
-
Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
|
|
7
|
-
|
|
8
|
-
Prompt binding: load `.codex/prompts/architect.md` first, then read the provided `review-packet` or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, and stop conditions override static prompt memory.
|
|
9
|
-
|
|
10
|
-
Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
|
|
11
|
-
|
|
12
|
-
Output: concise Simplified Chinese. Put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
|
|
13
|
-
"""
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
# oh-my-codex agent: critic
|
|
2
|
-
name = "critic"
|
|
3
|
-
description = "Plan/design critical challenge and review"
|
|
4
|
-
model_reasoning_effort = "xhigh"
|
|
5
|
-
developer_instructions = """
|
|
6
|
-
Role: Critic. Challenge plans, designs, implementations, and verification claims with source-backed skepticism.
|
|
7
|
-
|
|
8
|
-
Prompt binding: load `.codex/prompts/critic.md` first, then read the provided `review-packet` or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, and stop conditions override static prompt memory.
|
|
9
|
-
|
|
10
|
-
Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
|
|
11
|
-
|
|
12
|
-
Output: concise Simplified Chinese. State pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
|
|
13
|
-
"""
|
|
@@ -1,116 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"adapter": "codex",
|
|
3
|
-
"version": 1,
|
|
4
|
-
"mappings": [
|
|
5
|
-
{
|
|
6
|
-
"kind": "skill",
|
|
7
|
-
"source": "templates/workflow/skills/superspec-explore/SKILL.md",
|
|
8
|
-
"target": ".codex/skills/superspec-explore/SKILL.md"
|
|
9
|
-
},
|
|
10
|
-
{
|
|
11
|
-
"kind": "skill",
|
|
12
|
-
"source": "templates/workflow/skills/superspec-propose/SKILL.md",
|
|
13
|
-
"target": ".codex/skills/superspec-propose/SKILL.md"
|
|
14
|
-
},
|
|
15
|
-
{
|
|
16
|
-
"kind": "skill",
|
|
17
|
-
"source": "templates/workflow/skills/superspec-apply/SKILL.md",
|
|
18
|
-
"target": ".codex/skills/superspec-apply/SKILL.md"
|
|
19
|
-
},
|
|
20
|
-
{
|
|
21
|
-
"kind": "skill",
|
|
22
|
-
"source": "templates/workflow/skills/superspec-review/SKILL.md",
|
|
23
|
-
"target": ".codex/skills/superspec-review/SKILL.md"
|
|
24
|
-
},
|
|
25
|
-
{
|
|
26
|
-
"kind": "skill",
|
|
27
|
-
"source": "templates/workflow/skills/superspec-archive/SKILL.md",
|
|
28
|
-
"target": ".codex/skills/superspec-archive/SKILL.md"
|
|
29
|
-
},
|
|
30
|
-
{
|
|
31
|
-
"kind": "hook",
|
|
32
|
-
"source": "templates/hooks/codex-hooks.json",
|
|
33
|
-
"target": ".codex/hooks.json"
|
|
34
|
-
},
|
|
35
|
-
{
|
|
36
|
-
"kind": "prompt",
|
|
37
|
-
"source": "templates/workflow/prompts/architect.md",
|
|
38
|
-
"target": ".codex/prompts/architect.md"
|
|
39
|
-
},
|
|
40
|
-
{
|
|
41
|
-
"kind": "prompt",
|
|
42
|
-
"source": "templates/workflow/prompts/code-reviewer.md",
|
|
43
|
-
"target": ".codex/prompts/code-reviewer.md"
|
|
44
|
-
},
|
|
45
|
-
{
|
|
46
|
-
"kind": "prompt",
|
|
47
|
-
"source": "templates/workflow/prompts/critic.md",
|
|
48
|
-
"target": ".codex/prompts/critic.md"
|
|
49
|
-
},
|
|
50
|
-
{
|
|
51
|
-
"kind": "prompt",
|
|
52
|
-
"source": "templates/workflow/prompts/executor.md",
|
|
53
|
-
"target": ".codex/prompts/executor.md"
|
|
54
|
-
},
|
|
55
|
-
{
|
|
56
|
-
"kind": "prompt",
|
|
57
|
-
"source": "templates/workflow/prompts/explore.md",
|
|
58
|
-
"target": ".codex/prompts/explore.md"
|
|
59
|
-
},
|
|
60
|
-
{
|
|
61
|
-
"kind": "prompt",
|
|
62
|
-
"source": "templates/workflow/prompts/test-runner.md",
|
|
63
|
-
"target": ".codex/prompts/test-runner.md"
|
|
64
|
-
},
|
|
65
|
-
{
|
|
66
|
-
"kind": "prompt",
|
|
67
|
-
"source": "templates/workflow/prompts/test-engineer.md",
|
|
68
|
-
"target": ".codex/prompts/test-engineer.md"
|
|
69
|
-
},
|
|
70
|
-
{
|
|
71
|
-
"kind": "prompt",
|
|
72
|
-
"source": "templates/workflow/prompts/verifier.md",
|
|
73
|
-
"target": ".codex/prompts/verifier.md"
|
|
74
|
-
},
|
|
75
|
-
{
|
|
76
|
-
"kind": "agent",
|
|
77
|
-
"source": "adapters/codex/agents/architect.toml",
|
|
78
|
-
"target": ".codex/agents/architect.toml"
|
|
79
|
-
},
|
|
80
|
-
{
|
|
81
|
-
"kind": "agent",
|
|
82
|
-
"source": "adapters/codex/agents/code-reviewer.toml",
|
|
83
|
-
"target": ".codex/agents/code-reviewer.toml"
|
|
84
|
-
},
|
|
85
|
-
{
|
|
86
|
-
"kind": "agent",
|
|
87
|
-
"source": "adapters/codex/agents/critic.toml",
|
|
88
|
-
"target": ".codex/agents/critic.toml"
|
|
89
|
-
},
|
|
90
|
-
{
|
|
91
|
-
"kind": "agent",
|
|
92
|
-
"source": "adapters/codex/agents/explore.toml",
|
|
93
|
-
"target": ".codex/agents/explore.toml"
|
|
94
|
-
},
|
|
95
|
-
{
|
|
96
|
-
"kind": "agent",
|
|
97
|
-
"source": "adapters/codex/agents/executor.toml",
|
|
98
|
-
"target": ".codex/agents/executor.toml"
|
|
99
|
-
},
|
|
100
|
-
{
|
|
101
|
-
"kind": "agent",
|
|
102
|
-
"source": "adapters/codex/agents/test-runner.toml",
|
|
103
|
-
"target": ".codex/agents/test-runner.toml"
|
|
104
|
-
},
|
|
105
|
-
{
|
|
106
|
-
"kind": "agent",
|
|
107
|
-
"source": "adapters/codex/agents/test-engineer.toml",
|
|
108
|
-
"target": ".codex/agents/test-engineer.toml"
|
|
109
|
-
},
|
|
110
|
-
{
|
|
111
|
-
"kind": "agent",
|
|
112
|
-
"source": "adapters/codex/agents/verifier.toml",
|
|
113
|
-
"target": ".codex/agents/verifier.toml"
|
|
114
|
-
}
|
|
115
|
-
]
|
|
116
|
-
}
|
package/bin/launch.js
DELETED
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
export const REQUIRED_NODE_VERSION = "20.19.0";
|
|
2
|
-
const REQUIRED_NODE_PARTS = REQUIRED_NODE_VERSION.split(".").map((part) => Number.parseInt(part, 10));
|
|
3
|
-
|
|
4
|
-
function compareNodeVersion(version) {
|
|
5
|
-
const parts = String(version).split(".").map((part) => Number.parseInt(part, 10));
|
|
6
|
-
for (let index = 0; index < REQUIRED_NODE_PARTS.length; index += 1) {
|
|
7
|
-
const actual = parts[index] ?? 0;
|
|
8
|
-
const required = REQUIRED_NODE_PARTS[index] ?? 0;
|
|
9
|
-
if (!Number.isFinite(actual)) return -1;
|
|
10
|
-
if (actual > required) return 1;
|
|
11
|
-
if (actual < required) return -1;
|
|
12
|
-
}
|
|
13
|
-
return 0;
|
|
14
|
-
}
|
|
15
|
-
|
|
16
|
-
export function nodeVersionError(version = process.versions.node) {
|
|
17
|
-
if (compareNodeVersion(version) >= 0) return null;
|
|
18
|
-
return `SuperSpec requires Node.js >=${REQUIRED_NODE_VERSION}. Current Node.js is ${version}. Upgrade Node.js, then rerun the command.`;
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
export function assertSupportedNode(version = process.versions.node) {
|
|
22
|
-
const message = nodeVersionError(version);
|
|
23
|
-
if (message === null) return;
|
|
24
|
-
console.error(message);
|
|
25
|
-
process.exit(1);
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
export async function runEntry(entryPath, exportName, argv = process.argv.slice(2)) {
|
|
29
|
-
assertSupportedNode();
|
|
30
|
-
const mod = await import(new URL(entryPath, import.meta.url).href);
|
|
31
|
-
const main = mod[exportName];
|
|
32
|
-
if (typeof main !== "function") {
|
|
33
|
-
console.error(`SuperSpec internal error: ${entryPath} does not export ${exportName}`);
|
|
34
|
-
process.exit(2);
|
|
35
|
-
}
|
|
36
|
-
process.exitCode = await main(argv);
|
|
37
|
-
}
|
package/bin/superspec-check.js
DELETED
package/bin/superspec-hook.js
DELETED
package/bin/superspec-init.js
DELETED
package/bin/superspec.js
DELETED