comet-dsh-plugin 0.0.0-stage → 0.5.4
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/LICENSE +21 -0
- package/README.en.md +176 -0
- package/README.md +152 -2
- package/client.js +349 -0
- package/cordis.patch.yml +4 -0
- package/icon.png +0 -0
- package/index.js +183 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +58 -4
- package/rules/comet-workflow-guard.md +65 -0
- package/rules/migration-assets.json +218 -0
- package/server/comet-plugin-setup.mjs +192 -0
- package/skills/comet/SKILL.md +37 -0
- package/skills/comet/agents/openai.yaml +3 -0
- package/skills/comet/reference/change-walkthrough.md +77 -0
- package/skills/comet/reference/edit-review.md +26 -0
- package/skills/comet/reference/host-check.md +11 -0
- package/skills/comet/reference/platform-execution.md +34 -0
- package/skills/comet/reference/task-learning.md +39 -0
- package/skills/comet/runtime/classic/checks.yaml +6 -0
- package/skills/comet/runtime/classic/guardrails.yaml +13 -0
- package/skills/comet/runtime/classic/skill.yaml +122 -0
- package/skills/comet/scripts/comet-archive.mjs +310 -0
- package/skills/comet/scripts/comet-check.mjs +179 -0
- package/skills/comet/scripts/comet-entry-runtime.mjs +151 -0
- package/skills/comet/scripts/comet-env.mjs +15 -0
- package/skills/comet/scripts/comet-guard.mjs +335 -0
- package/skills/comet/scripts/comet-handoff.mjs +289 -0
- package/skills/comet/scripts/comet-hook-guard.mjs +295 -0
- package/skills/comet/scripts/comet-hook-router-guard.mjs +629 -0
- package/skills/comet/scripts/comet-hook-router.mjs +17 -0
- package/skills/comet/scripts/comet-intent.mjs +181 -0
- package/skills/comet/scripts/comet-plugin-hook.mjs +213 -0
- package/skills/comet/scripts/comet-resume-probe.mjs +205 -0
- package/skills/comet/scripts/comet-runtime.mjs +572 -0
- package/skills/comet/scripts/comet-state.mjs +381 -0
- package/skills/comet/scripts/comet-yaml-validate.mjs +182 -0
- package/skills/comet-any/SKILL.md +47 -0
- package/skills/comet-any/agents/openai.yaml +5 -0
- package/skills/comet-any/reference/sdk-creation.md +100 -0
- package/skills/comet-archive/SKILL.md +28 -0
- package/skills/comet-archive/agents/openai.yaml +5 -0
- package/skills/comet-archive/reference/compat.md +188 -0
- package/skills/comet-build/SKILL.md +35 -0
- package/skills/comet-build/agents/openai.yaml +5 -0
- package/skills/comet-build/reference/compat.md +191 -0
- package/skills/comet-classic/SKILL.md +98 -0
- package/skills/comet-classic/agents/openai.yaml +3 -0
- package/skills/comet-classic/reference/auto-transition.md +34 -0
- package/skills/comet-classic/reference/classic-layout.md +36 -0
- package/skills/comet-classic/reference/comet-yaml-fields.md +82 -0
- package/skills/comet-classic/reference/context-recovery.md +128 -0
- package/skills/comet-classic/reference/debug-gate.md +30 -0
- package/skills/comet-classic/reference/decision-point.md +109 -0
- package/skills/comet-classic/reference/dirty-worktree.md +59 -0
- package/skills/comet-classic/reference/file-structure.md +32 -0
- package/skills/comet-classic/reference/intent-frame.md +132 -0
- package/skills/comet-classic/reference/scripts.md +144 -0
- package/skills/comet-classic/reference/sdk-methods.md +136 -0
- package/skills/comet-classic/reference/subagent-dispatch.md +75 -0
- package/skills/comet-classic/reference/workspace.md +23 -0
- package/skills/comet-design/SKILL.md +25 -0
- package/skills/comet-design/agents/openai.yaml +5 -0
- package/skills/comet-design/reference/compat.md +191 -0
- package/skills/comet-hotfix/SKILL.md +46 -0
- package/skills/comet-hotfix/agents/openai.yaml +5 -0
- package/skills/comet-hotfix/reference/compat.md +240 -0
- package/skills/comet-memory/SKILL.md +68 -0
- package/skills/comet-memory/agents/openai.yaml +5 -0
- package/skills/comet-native/SKILL.md +139 -0
- package/skills/comet-native/agents/openai.yaml +3 -0
- package/skills/comet-native/reference/artifacts.md +118 -0
- package/skills/comet-native/reference/clarification.md +120 -0
- package/skills/comet-native/reference/commands.md +321 -0
- package/skills/comet-native/reference/edit-review.md +26 -0
- package/skills/comet-native/reference/recovery.md +64 -0
- package/skills/comet-native/reference/workspace.md +70 -0
- package/skills/comet-native/scripts/comet-native-archive.mjs +475 -0
- package/skills/comet-native/scripts/comet-native-cancel.mjs +461 -0
- package/skills/comet-native/scripts/comet-native-doctor.mjs +475 -0
- package/skills/comet-native/scripts/comet-native-hook-guard.mjs +470 -0
- package/skills/comet-native/scripts/comet-native-init.mjs +465 -0
- package/skills/comet-native/scripts/comet-native-new.mjs +478 -0
- package/skills/comet-native/scripts/comet-native-next.mjs +470 -0
- package/skills/comet-native/scripts/comet-native-root.mjs +472 -0
- package/skills/comet-native/scripts/comet-native-runtime.mjs +525 -0
- package/skills/comet-native/scripts/comet-native-select.mjs +468 -0
- package/skills/comet-native/scripts/comet-native-show.mjs +462 -0
- package/skills/comet-native/scripts/comet-native-spec.mjs +468 -0
- package/skills/comet-native/scripts/comet-native-status.mjs +467 -0
- package/skills/comet-native/scripts/comet-native-transfer.mjs +466 -0
- package/skills/comet-open/SKILL.md +265 -0
- package/skills/comet-open/agents/openai.yaml +5 -0
- package/skills/comet-open/reference/batch-changes.md +51 -0
- package/skills/comet-review/SKILL.md +121 -0
- package/skills/comet-review/agents/openai.yaml +5 -0
- package/skills/comet-tweak/SKILL.md +49 -0
- package/skills/comet-tweak/agents/openai.yaml +5 -0
- package/skills/comet-tweak/reference/compat.md +232 -0
- package/skills/comet-verify/SKILL.md +30 -0
- package/skills/comet-verify/agents/openai.yaml +5 -0
- package/skills/comet-verify/reference/compat.md +202 -0
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# comet-build Compat 操作
|
|
2
|
+
|
|
3
|
+
仅在 `runtimeFormat: compat` 时读取。SDK 使用主 Skill 与 SDK 方法参考。
|
|
4
|
+
|
|
5
|
+
## 前置条件
|
|
6
|
+
|
|
7
|
+
- Design Doc 已创建(阶段 2 完成)
|
|
8
|
+
- 活跃 change 存在
|
|
9
|
+
|
|
10
|
+
## 步骤
|
|
11
|
+
|
|
12
|
+
### 0. 入口状态验证(Entry Check)
|
|
13
|
+
|
|
14
|
+
按 `comet-classic/reference/scripts.md` 使用正式支持的 `comet` CLI,执行以下入口验证。从任意入口恢复任务时,先按 `comet-classic/reference/context-recovery.md` 检查恢复状态:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
comet state select <change-name>
|
|
18
|
+
comet state check <name> build --json
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
本轮 Design/Guard 已成功返回 Build 状态信息时,直接使用其中的 `data.configuration`、`configurationReadiness`、`artifactRefs` 和任务信息,并按 `agent.continuation` 继续,不重复 select/check。恢复任务、工作区变化或外部状态变化时,才执行上述入口验证。配置写入成功后,使用返回的结果,不逐字段重复调用 get;验证失败时处理 `data.issues`。
|
|
22
|
+
|
|
23
|
+
若上述 `select` / `check` 输出 `BLOCKED` 或分支绑定 `ERROR`,且原因是 `bound_branch` 与当前分支不一致,立即按 `comet-classic/reference/decision-point.md` 暂停,让用户单选:切回绑定分支后重新运行入口验证,或在用户明确确认当前分支应接管该 change 后运行 `comet state rebind <change-name>` 并重新入口验证。不得自行切换分支,不得自行换绑。
|
|
24
|
+
|
|
25
|
+
**恢复**:根据入口返回的 phase、任务 ID 和 plan 的 `base-ref`,核对现有实现与审查记录,再从尚未完成的实施或审查步骤继续。任务未勾选不等于尚未实现。派发任务前先核对检查点,不重复已有提交,也不假定外部操作可以安全重试。
|
|
26
|
+
|
|
27
|
+
### 1. 先确认执行策略
|
|
28
|
+
|
|
29
|
+
需要展示、补齐或更改配置时,先读取[执行配置展示](../../comet-classic/reference/decision-point.md#执行配置展示),呈现当前 change 的值、含义和确认状态;保存仍使用本节 Compat 命令。
|
|
30
|
+
|
|
31
|
+
读取入口返回的 configuration、`configurationReadiness`、taskState 和 nextAction。`configurationReadiness.missingFields` 与 `invalidFields` 均为空且用户未要求更改时,沿用已确认配置,不重新列成待选择问题;只有缺失、无效或用户要求更改的字段才补问对应决定。已有计划和审查记录仍然有效时直接继续,不重新询问或生成。工作区必须已在 Open 阶段准备并绑定;缺少 isolation 或目录不匹配时停止,回到 workspace resolve 返回的 projectRoot 恢复任务,不能在 Build 新建或切换工作区。
|
|
32
|
+
|
|
33
|
+
**写计划前必须确认执行策略**。`configurationReadiness` 只列出尚未确定或组合无效的字段;配置已经有效且用户未要求更改时不重复询问。配置缺失、无效或用户明确要求更改时,按 `comet-classic/reference/decision-point.md` 在同一轮提问中收集执行方式、TDD 和审查模式,但只询问 `missingFields` 和 `invalidFields` 中列出的决定,以及用户明确要求更改的字段,不按模型名称自动选择:
|
|
34
|
+
|
|
35
|
+
| build_mode | 行为 |
|
|
36
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
37
|
+
| `autonomous` | 用户明确选择后,Agent 自行制定计划;可以串行实施,也可以将范围明确的一组任务委派给子代理,不强制加载外部规划或执行 Skill |
|
|
38
|
+
| `subagent-driven-development` | 加载同名 Superpowers Skill;主会话负责协调,实现代理(implementer)负责实施,并遵守 Comet 的任务派发与审查规则 |
|
|
39
|
+
| `executing-plans` | 加载同名 Superpowers Skill,由主会话按计划顺序实施 |
|
|
40
|
+
|
|
41
|
+
Agent 具备较强的自主规划能力、任务较长且需要灵活安排时,可推荐 autonomous;希望遵循固定的委派方法时,推荐 subagent-driven-development;希望按固定顺序执行计划时,推荐 executing-plans。推荐不能代替用户确认,也不自动替换已有 change 的执行策略。
|
|
42
|
+
|
|
43
|
+
| 配置 | 选项与约束 |
|
|
44
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
45
|
+
| `tdd_mode` | `tdd`:先确认测试因待实现的行为而失败(RED),再实施并使测试通过(GREEN);`direct`:不强制逐任务 RED/GREEN,但仍需相关测试和缺陷回归结果 |
|
|
46
|
+
| `review_mode` | `off`:低风险任务不自动审查;`standard`:审查有风险的任务,并在 Verify 完成唯一一次最终集成审查;`thorough`:按已选执行方式逐任务或分段独立审查,并完成最终集成审查 |
|
|
47
|
+
|
|
48
|
+
full 流程采用 autonomous 时,必须选择 standard 或 thorough,不能用实现者自评代替独立审查。已有执行策略仍遵循原有 review_mode 规则。TDD 默认推荐 tdd,审查默认推荐 standard;hotfix/tweak 的 direct 预设保持不变。
|
|
49
|
+
|
|
50
|
+
用户完成所有选择后,在一次原子操作中写入配置。例如,用户明确选择自主执行、TDD 和 standard 审查时:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
comet state set <name> build_mode autonomous subagent_dispatch null tdd_mode tdd review_mode standard --json
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
将示例替换为用户的实际选择。选择 subagent-driven-development 时,同时写入 `subagent_dispatch confirmed`;其他方式写入 null。保留 isolation、bound_branch 和已有暂停状态。写入失败时停止,不加载执行 Skill。用户尚未决定或要求暂停时停止,不写入不完整的配置。
|
|
57
|
+
|
|
58
|
+
`direct` 不是 autonomous 的别名:full 只有用户明确要求且记录 `direct_override true` 才允许 direct;不能借自主策略跳过设计、计划、配置、验证或独立审查。
|
|
59
|
+
|
|
60
|
+
### 2. 创建或恢复计划
|
|
61
|
+
|
|
62
|
+
任务是否完成,以 `tasks.md` 为准。需要读取各项任务的正文或 ID 时,才运行 `comet state tasks <name> --json`;缺少 ID 时运行 `comet state tasks <name> --assign-ids --json`。保留已有 ID,并更新受影响的 handoff 和计划中的任务映射。
|
|
63
|
+
|
|
64
|
+
恢复任务、同步旧计划中的勾选框或补记完成状态时,按 context-recovery.md 处理。任务未勾选不等于尚未实施:已经实现且检查、审查充分的任务可以补勾;其余任务只补未完成的工作。task-complete 会自动同步有 comet-task ID 映射的旧计划;需要单独同步时,使用 `comet state sync-plan <name>`。planSync 返回 mapping-required 时,只补任务映射,不重做实现。
|
|
65
|
+
|
|
66
|
+
已有有效计划时沿用。否则使用 configuration.language,在 `<classic-superpowers-root>/plans/<YYYY-MM-DD>-<change-name>.md` 创建计划:
|
|
67
|
+
|
|
68
|
+
- autonomous:由当前 Agent 直接编写和自检,不加载 writing-plans。
|
|
69
|
+
- 其他计划执行策略:使用 `writing-plans` Skill,只采用其编写和自检方法;技能失败则停止。传入已确认的配置、design_doc、tasks.md、固定计划路径和当前 `git rev-parse HEAD`。完成后返回 Comet Build,不再次选择执行策略,也不自动进入外部 Skill 的后续流程。
|
|
70
|
+
|
|
71
|
+
计划深度按风险调整:范围明确、方法成熟且易回退的任务简要记录;存在真实技术取舍、组件依赖、权限、迁移、并发、兼容性或不可逆操作时,补充方案理由、依赖、回退和验证。每个任务仍对应一个可独立验收的结果,列明 task ID、范围、依赖、约束,以及验收命令或场景;不按预计分钟数、文件数量或 RED/GREEN 步骤拆分任务。计划引用已有设计和需求,不预先写出完整实现;只有必须提前审查的接口或高风险算法,才提供必要的代码片段。
|
|
72
|
+
|
|
73
|
+
新计划不创建第二套 checkbox,写入 `<!-- comet-task-authority: <classic-task-authority-ref> -->`(取自 `data.artifactRefs.tasks` 的仓库相对引用),以 `<!-- comet-task-ref:<task-id> -->` 关联每个任务。计划新增实际任务必须先纳入 tasks.md 并分配 ID;范围变化按 Step 4 处理。
|
|
74
|
+
|
|
75
|
+
计划文件头:
|
|
76
|
+
|
|
77
|
+
```yaml
|
|
78
|
+
---
|
|
79
|
+
change: <change-name>
|
|
80
|
+
design-doc: <recorded-design-doc-path>
|
|
81
|
+
base-ref: <git rev-parse HEAD before implementation>
|
|
82
|
+
---
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
保留旧计划 base-ref,不在恢复时替换为当前 HEAD。`<plan-ref>` 沿用 `data.artifactRefs.plan`,新计划使用 `data.artifactRefs.plansRoot` 与已选文件名组成的仓库相对引用;绝对路径仅用于写文件。确认文件存在后记录:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
comet state set <name> plan "<plan-ref>" --json
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
计划完成后,默认按已确认的策略继续,不再追加配置确认。用户明确要求切换模型,或要求写完计划后暂停时,写入 `comet state set <name> build_pause plan-ready` 并停止。恢复已有 plan-ready 暂停时,只有用户明确要求继续,才清除暂停状态。沿用仍然有效的计划和配置;旧 change 缺少配置时补做 Step 1,不重写计划。
|
|
92
|
+
|
|
93
|
+
### 3. 执行与验收
|
|
94
|
+
|
|
95
|
+
执行前使用本轮入口配置和 continuation;配置、需求或工作区变化后刷新入口。按风险执行相关检查,不在每个小修改后重复全量验证;外部 Skill 只执行当前计划和确认配置,不新建 Worktree、重新选择隔离、追加最终审查或调用 finishing-a-development-branch;完成任务返回 Comet Build。
|
|
96
|
+
|
|
97
|
+
- autonomous:Agent 在计划范围内自行组织实施。需要委派时,先读取 `comet-classic/reference/subagent-dispatch.md`,将范围明确的一组任务作为工作包交给子代理,通过 Runtime 保存协调记录,并安排独立审查者(reviewer);不强制加载外部执行 Skill。
|
|
98
|
+
- executing-plans:使用 Skill 工具加载 Superpowers `executing-plans`,传入入口 configuration.language,按计划顺序执行;加载失败则停止。
|
|
99
|
+
- subagent-driven-development:加载同名 Superpowers Skill 和 `comet-classic/reference/subagent-dispatch.md`。主会话负责协调,不代替实现代理编写代码;派发失败时保存 BLOCKED 原因,不能擅自接管实现或更改策略。
|
|
100
|
+
|
|
101
|
+
配置为 tdd 时,每个实现任务都必须记录 RED 和对应 GREEN 的命令及真实结果,并确认 RED 的失败原因就是待实现的行为。autonomous 无需加载外部 TDD Skill,但仍须完成 RED/GREEN;executing-plans 在首次实施前加载一次 test-driven-development,子代理策略则由实现代理加载。上下文完整时不重复加载;丢失上下文后恢复任务时,先核对已有结果,不重演已经验证的实现过程,也不回退代码伪造 RED。direct 模式仍需相关检查与缺陷回归结果。
|
|
102
|
+
|
|
103
|
+
Build 只做任务或分段审查,Verify 负责唯一最终集成审查:
|
|
104
|
+
|
|
105
|
+
- autonomous 及子代理执行:按 subagent-dispatch.md 的风险分级和复查次数限制进行独立任务审查;autonomous 即使不委派实现,也必须由独立审查者完成所需审查。
|
|
106
|
+
- executing-plans + off|standard:验收任务后进入 Verify,不追加 Build 最终审查。
|
|
107
|
+
- executing-plans + thorough:每个任务都须纳入独立审查;依赖紧密、必须共同验收的任务可组成一段,按可独立验收的结果与风险边界审查 diff,不按固定任务数量切段。各段通过审查后才继续依赖它的后续实施,不将可独立验收的全部任务合成一段延后审查。没有后续实施的最后一段交由 Verify 的唯一最终集成审查。
|
|
108
|
+
|
|
109
|
+
必须解决 CRITICAL/IMPORTANT 问题。无法进行独立审查时停止,不能用自评代替。对于已接受的非关键偏差,记录接受依据和影响范围。验收后,使用 task-complete 按任务 ID 逐项勾选 tasks.md;通过 `comet state checkpoint <name> --file <json-path>` 保存协作与恢复记录,字段与读写规则见 context-recovery.md。检查点不能代替任务勾选或实际检查、审查结果。
|
|
110
|
+
|
|
111
|
+
### 3b. 执行中异常调试(异常调试协议)
|
|
112
|
+
|
|
113
|
+
执行任务期间,出现非预期的崩溃、异常行为、测试失败或构建失败,必须先调查根因;autonomous 直接遵循异常调试协议,其他策略加载 Superpowers `systematic-debugging`。根因未明前不得实施源码修复。已核对因待实现行为而失败的 TDD RED 是正常证据;加载错误、环境错误、无关回归或原因不明的 RED 仍须调查。
|
|
114
|
+
|
|
115
|
+
根因调查、最小失败测试、修复后的验证,以及如何在当前 change 中完成这些步骤,均按 `comet-classic/reference/debug-gate.md` 执行。
|
|
116
|
+
|
|
117
|
+
### 4. Spec 增量更新
|
|
118
|
+
|
|
119
|
+
需求或验收变化需要重新确认时,先读取[需求变化后的重新确认](../../comet-classic/reference/decision-point.md#需求变化后的重新确认),说明变化及影响,再展示完整当前方案;实际更新与批准仍按下方规模分级处理。
|
|
120
|
+
|
|
121
|
+
实施过程中发现初版 spec 不完整时,按变更规模分级处理:
|
|
122
|
+
|
|
123
|
+
已确认范围内、不改变公开行为和验收约束的实现细节调整,只更新实施计划及理由,不重新开启 Open/Design。下面的分级规则仅用于真实规格或范围变化。
|
|
124
|
+
|
|
125
|
+
| 规模 | 触发条件 | 做法 |
|
|
126
|
+
| ---- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md,追加 tasks.md 任务 |
|
|
128
|
+
| 中 | 接口变更、新增组件、数据流变化 | **按 `comet-classic/reference/decision-point.md` 暂停并等待用户明确确认**,给出「继续按此更新设计」或「调整变更要求」两个选项;未确认不得重开设计。确认后,必须使用 Skill 工具加载 Superpowers `brainstorming` 更新 Design Doc + delta spec |
|
|
129
|
+
| 大 | 全新的功能需求 | **暂停、展示拆分选择并等待用户明确确认**;用户确认后,通过 `/comet-open` 创建独立 change |
|
|
130
|
+
|
|
131
|
+
**范围复核**:新增任务前,先核对原目标、公开行为、验收要求,以及用户已接受的风险。补充原范围内遗漏的实现或验收、调整任务粒度时,直接更新任务并记录依据;任务数量或增长比例本身不触发暂停。只有实际扩大范围、需要重新设计或出现可独立交付的新功能时,才按 `comet-classic/reference/decision-point.md` 暂停,让用户确认继续、调整还是拆分。
|
|
132
|
+
|
|
133
|
+
创建独立 change 时必须调用 `/comet-open`,不得直接调用 `/opsx:new`。`/comet-open` 会同时创建 OpenSpec 产物和 `.comet.yaml`,避免新 change 脱离 Comet 状态机。
|
|
134
|
+
|
|
135
|
+
**用户选择必须包含**:
|
|
136
|
+
|
|
137
|
+
- 「拆分为新 change」— 通过 `/comet-open` 创建独立 change
|
|
138
|
+
- 「继续在当前 change 内完成」— 记录范围扩展决策,更新 tasks.md 和 delta spec 后继续
|
|
139
|
+
|
|
140
|
+
**原则**:
|
|
141
|
+
|
|
142
|
+
- delta spec 随实现进展持续维护,在本阶段可按上述规则修改
|
|
143
|
+
- 每次更新应提交,commit message 说明变更原因
|
|
144
|
+
- 不提前同步到 main spec,归档时统一同步
|
|
145
|
+
- 小规模增量直接改 delta spec 时,应在 commit message 中注明,便于归档时判断 design doc 漂移
|
|
146
|
+
|
|
147
|
+
**handoff 更新**:由 Agent 判断交接上下文是否仍能准确说明当前需求。需要更新时运行 `comet handoff <change-name> design --write`,继续原 Build;不计算或比较交接内容摘要,不因文件编辑自动撤回批准。
|
|
148
|
+
|
|
149
|
+
### 5. 上下文管理
|
|
150
|
+
|
|
151
|
+
Build 是最长阶段,可能跨越大量任务。为支持上下文压缩后断点恢复:
|
|
152
|
+
|
|
153
|
+
- **每完成一个 task**:按配置核对实际实现、检查和审查后,用 `comet state task-complete <name> <task-id> --json` 勾选 tasks.md。按稳定 task ID 记录真实完成结果;任务要求变化时由 Agent 重新判断实际影响。新计划和检查点不复制 checkbox;旧计划只同步有明确 ID 映射的完成项,按 context-recovery.md 处理。工作包逐 ID 验收,使用 checkpoint 命令持久化协调记录,按项目提交策略保存进度。
|
|
154
|
+
- **上下文压缩后恢复**:按 `comet-classic/reference/context-recovery.md` 执行,phase 参数为 `build`。
|
|
155
|
+
- **用户手动修改恢复**:按 `comet-classic/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理:
|
|
156
|
+
1. 归因后,若 diff 暗示计划或 spec 已变化,按 Step 4「Spec 增量更新」分级处理
|
|
157
|
+
- **长任务拆分**:按可独立验收的结果和任务依赖关系拆分;代码行数只用于提示审查风险,不单独决定任务数量
|
|
158
|
+
|
|
159
|
+
## 退出条件
|
|
160
|
+
|
|
161
|
+
- tasks.md 全部勾选
|
|
162
|
+
- 代码已提交
|
|
163
|
+
- 已显式运行项目对应的构建/测试命令并通过(不要只依赖 guard 自动猜测)
|
|
164
|
+
- `isolation` 已写为 `current`、`branch` 或 `worktree`
|
|
165
|
+
- `build_mode` 已写为 `autonomous`、`subagent-driven-development`、`executing-plans` 或带显式 override 的 `direct`;若为 `subagent-driven-development`,`subagent_dispatch` 必须为 `confirmed`;full autonomous 必须保留有效设计、计划及 standard/thorough 独立审查
|
|
166
|
+
- `tdd_mode` 已写为 `tdd` 或 `direct`
|
|
167
|
+
- `review_mode` 已写为 `off`、`standard` 或 `thorough`
|
|
168
|
+
- 已完成 `review_mode` 要求的任务级或分段审查;不在 Build 重复 Verify 的最终集成审查
|
|
169
|
+
- **阶段守卫**:运行 `comet guard <change-name> build --apply`,全部 PASS 后由守卫推进到 `phase: verify`(此步骤更新 `phase` 字段,与 `auto_transition` 无关)
|
|
170
|
+
|
|
171
|
+
按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 平台检查结束后用 `state record-check` 记录真实退出码,再运行阶段守卫。Guard 核对配置、任务、产物和报告,不执行检查。任务勾选继续用 `state task-complete`。`COMET_SKIP_BUILD=1` 不作为验收证据。
|
|
172
|
+
|
|
173
|
+
退出前运行阶段守卫推进 phase(此步骤与 `auto_transition` 无关):
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
comet guard <change-name> build --apply
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
状态文件自动更新为 `phase: verify`、`verify_result: pending`。
|
|
180
|
+
|
|
181
|
+
## 自动衔接下一阶段
|
|
182
|
+
|
|
183
|
+
按 `comet-classic/reference/auto-transition.md` 和成功结果中的 `agent.continuation` 继续。已有仍然有效的状态信息时,不重复 next、select 或 check。只有丢失上下文后恢复任务、外部状态变化,或旧结果未提供这些信息时,才运行:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
comet state next <change-name>
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
- `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
|
|
190
|
+
- `NEXT: manual` → 不调用下一 skill,按 `HINT` 交还控制权并结束当前调用;不再创建确认点
|
|
191
|
+
- `NEXT: done` → 流程已完成,无需继续
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comet-classic
|
|
3
|
+
description: 'Comet Classic 工作流入口。当用户明确调用 /comet-classic、要求启动或恢复 Classic,或 resume-probe 返回 auto_resume、确认唯一可恢复的未归档 Classic change 时使用。'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Comet Classic — OpenSpec + Superpowers
|
|
7
|
+
|
|
8
|
+
Classic 分为 Open → Design → Build → Verify → Archive 五个阶段。OpenSpec 管理需求规格与归档,Superpowers 提供设计方法,以及用户选定的规划、执行和审查方法。完整流程(full)必须经过 brainstorming 和设计确认;hotfix/tweak 使用各自的预设步骤。
|
|
9
|
+
|
|
10
|
+
## 1. 确定目标与工作区
|
|
11
|
+
|
|
12
|
+
开始新任务或更换宿主时,必须读取并执行[宿主能力核对](../comet/reference/host-check.md),在批准 Open 前确认当前流程所需的能力。执行配置改变后,只补核对新策略需要的能力。
|
|
13
|
+
|
|
14
|
+
开始或恢复前,按 `comet-classic/reference/classic-layout.md` 解析产物路径,并执行 `comet-classic/reference/scripts.md` 的“CLI 引导”。使用公开 Comet CLI 和 OpenSpec 适配器。所有参考按当前动作读取相关章节,复用上下文中仍有效的规则。
|
|
15
|
+
|
|
16
|
+
- 未明确调用 Classic、需要判定是否恢复已有工作时:读取 `comet-classic/reference/context-recovery.md` 的 Ambient Resume,按 `comet resume-probe . --stdin --json` 结果处理;只有 `auto_resume` 自动进入,`ask_user` 按 `reason` 使用 Ambient Resume 表格中的问题与选项提问,`out_of_scope`/`none` 不进入。
|
|
17
|
+
- 启动新需求或目标 change 尚不明确时:读取 `comet-classic/reference/intent-frame.md` 的最小示例与目标选择规则,获取未归档的 change 列表后填写 CometIntentFrame,运行 `comet classic intent route --stdin`。Agent 只负责按证据填写意图字段,路由由 Runtime 计算;以返回结果为准,不另写一套自然语言评分规则。
|
|
18
|
+
- 已明确目标 change 且已由 Runtime 初始化时:按下方绑定工作区;SDK 新 change 使用 `comet-state.yaml`,历史 `.comet.yaml` 原地读写,compat 初始化仍使用旧名,以 `state next` 返回的 Runtime 归属判断恢复路径,不能只看状态文件是否存在。有多个未归档的 change 且尚未选定时,不提前绑定。真正的新 change 直接交 `/comet-open` 或对应预设 Skill,它们会先准备工作区再初始化;`workspace resolve` 对未初始化的 change 会报 not found。
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
comet classic workspace resolve <change-name> --json
|
|
22
|
+
# 进入返回的 projectRoot 后选择 change
|
|
23
|
+
comet state select <change-name> --json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
同一 change 同时存在 `comet-state.yaml` 和 `.comet.yaml` 时(包括其中一个是失效符号链接)必须停止,保留两个文件并核对来源;不得静默择一、覆盖或自动改名。
|
|
27
|
+
|
|
28
|
+
选择结果已包含当前 Runtime 归属、phase、revision 与 nextAction 时直接继续;只有缺少信息、外部状态变化或旧结果已过期时,才运行 `comet state next <change-name> --json` 补读。
|
|
29
|
+
|
|
30
|
+
跨设备同步应携带实际状态文件、change 文档、引用工件、代码和项目配置;检查点不包含独立子 worktree 和未提交代码。复制到新设备的 SDK change 若在实际状态文件中有 `run_checkpoint`,具名 `state select` 或 `state next` 会恢复原阶段、Action 和确认;继续外部工作前先确认原设备的执行进程已停止。结果未明的 Action 先核对,不重发。只有旧状态文件缺少检查点、常规入口明确报告 Run 记录丢失时,才核对正式文档,说明显式恢复会回到 Open、旧确认和检查需要重做,取得用户同意后运行 `comet state restore <change-name> --confirmed`。
|
|
31
|
+
|
|
32
|
+
发现普通或正式材料的实际文件变化,或续行提示编辑判断时,先读取并执行[编辑后继续原流程](../comet/reference/edit-review.md),再处理阶段动作或修订命令。修订命令不构成用户授权;缺少新增范围的授权时,保留原阶段、已接受结果和待办,只请求相关决定。
|
|
33
|
+
|
|
34
|
+
响应已有 `agent.continuation.mode` 时,先按 `comet-classic/reference/auto-transition.md` 的统一规则处理,以 `mode` 决定执行、等待、提问、核对或结束;下文的 `nextAction.kind` 路由仅用于没有 `mode` 的旧响应。
|
|
35
|
+
|
|
36
|
+
以 `data.runtimeFormat` 区分 `sdk` 与 `compat`,并按返回的 phase、configuration 和 `data.nextAction.kind` 继续。SDK 的 `action` 才能加载返回的 Skill;`decision`、`evidence`、`reconcile` 先进入对应阶段的恢复步骤,核对同一 Run 的待决定项、待提交证据或已领取 Action,不能把它们当作未执行的 Skill 重跑。旧 change 保持原有阶段路由。新 full change 交 `/comet-open`,由它准备工作区、创建 OpenSpec 产物并初始化 SDK Run;已确认的 hotfix/tweak 分别交 `/comet-hotfix`、`/comet-tweak`,按各自预设完成初始化。不直接调用 `/opsx:new`。已有 change 的 Runtime 归属与文件冲突或格式异常时,按 context-recovery.md 的“入口错误与恢复”停止并核对,不根据现有产物猜测阶段或新建第二份状态。
|
|
37
|
+
|
|
38
|
+
新 full change 必须先确定工作区,再在 Open 阶段创建产物。full workflow 的 `isolation` 可为 `current`、`branch` 或 `worktree`;用户明确要求并行工作时准备 Worktree,其他情况按 `comet-classic/reference/workspace.md` 选择。hotfix/tweak 按各自初始化步骤确认并绑定工作区。恢复时使用已经绑定的工作区;分支归属发生变化时,根据用户已确认的选择执行 rebind,缺少有效授权时才询问。
|
|
39
|
+
|
|
40
|
+
## 2. 载入当前阶段
|
|
41
|
+
|
|
42
|
+
同一组任务复用命令结果和已有上下文;响应含当前状态与 `agent.continuation` 时直接继续。只有字段缺失、工作区切换、恢复时丢失上下文或外部状态变化时才重新查询。按改动风险选择检查,Verify 负责一次最终集成审查。
|
|
43
|
+
|
|
44
|
+
绑定工作区并取得 phase 后,以及阶段切换、换 Agent 或上下文恢复时,读取并执行 [任务上下文与产物语言](reference/scripts.md#任务上下文与产物语言),优先使用当前 continuation 或已领取 Action 的 `contextRequest` 获取快照;同一阶段连续执行不重复获取。按配置确定产物语言;根据 Context Manifest(上下文清单)中的摘要,只展开当前步骤还缺少的内容。实际使用某条内容后如实记录使用结果,任务结束时保存检查点。
|
|
45
|
+
|
|
46
|
+
记忆学习只提交可复用的用户信息;任务摘要、进展、命令输出和测试结果不写入个人记忆。任务结束前按任务上下文参考完成学习检查,并记录 `submitted`、`no-observation` 或 `not-run`。
|
|
47
|
+
|
|
48
|
+
项目经验与个人偏好分开保存:任务结束前,把当前项目中已验证且未来可复用的经验用 `comet knowledge remember` 写入项目记忆;用户偏好和稳定协作习惯才进入个人记忆。命令和过滤条件见 [任务上下文与产物语言](reference/scripts.md#任务上下文与产物语言)。
|
|
49
|
+
|
|
50
|
+
- 新 full / open:`/comet-open`:澄清范围、创建必需产物、请用户检查并确认
|
|
51
|
+
- design:`/comet-design`:完成技术取舍并确认正式设计
|
|
52
|
+
- build + full:`/comet-build`:恢复配置/计划,完成任务与所需审查
|
|
53
|
+
- hotfix / build + hotfix:`/comet-hotfix`:已有异常的局部修复
|
|
54
|
+
- tweak / build + tweak:`/comet-tweak`:单 change 轻量调整
|
|
55
|
+
- verify:`/comet-verify`:执行验收、修复后复验、完成唯一一次最终集成审查
|
|
56
|
+
- archive / verify_result: pass:`/comet-archive`:确认归档、只提交当前 change 的文件、完成用户选定的交付方式
|
|
57
|
+
|
|
58
|
+
阶段工作由对应 Skill 执行;编写产物、调用 OpenSpec 或推进前先加载它。`decision`、`evidence` 和 `reconcile` 沿用当前 Run,不重做阶段工作。
|
|
59
|
+
|
|
60
|
+
新 full / Open,或当前 Action 指定 `comet-open` 时:
|
|
61
|
+
|
|
62
|
+
**立即执行:** 使用 Skill 工具加载 comet-open 技能。禁止跳过此步骤。
|
|
63
|
+
|
|
64
|
+
当前 Action 指定 `comet-design` 时:
|
|
65
|
+
|
|
66
|
+
**立即执行:** 使用 Skill 工具加载 comet-design 技能。禁止跳过此步骤。
|
|
67
|
+
|
|
68
|
+
只有新需求才考虑推荐轻量流程:风险符合预设要求且用户已明确选择时直接进入;由 Agent 推荐时,说明依据,并展示 hotfix/tweak 与保留 full 的选项及各自影响,等待用户确认。不得擅自把已有 full change 改成轻量流程。公共 API、数据迁移、安全、并发或跨模块设计应按实际风险处理,不能因为文件少就省略必要步骤。
|
|
69
|
+
|
|
70
|
+
运行 hotfix/tweak 时,SDK 必须读取并执行[预设范围复核](reference/sdk-methods.md#预设范围复核),按该节核对并复用仍有效的 `rulings.md` 授权;Compat 读取所选预设的 `reference/compat.md` 中“升级判定”。仅文件数超限时先核对范围和已有授权,需要新决定时才展示继续预设或升级 full 的选项。用户选择升级后,使用当前 Run 的 continuation 或 Compat 对应命令推进。`verify_mode` 只决定验证级别,不能替代 workflow 选择或预设升级确认。
|
|
71
|
+
|
|
72
|
+
恢复会话、外部状态变化,或计划、任务、审查、交付记录与实际情况不一致时,读取 `comet-classic/reference/context-recovery.md`,根据当前阶段入口返回的 nextAction 确定还有哪些步骤未完成。沿用仍有效的配置和成果;任务未勾选不等于尚未实现。具体恢复步骤以该参考文件为准。
|
|
73
|
+
|
|
74
|
+
## 3. 继续完成本次获准执行的工作
|
|
75
|
+
|
|
76
|
+
阶段退出检查通过后,按 `comet-classic/reference/auto-transition.md` 读取成功结果中的 `agent.continuation`,只加载它指定的下一 Skill。没有可复用的状态信息、会话恢复时缺少上下文,或发生外部变化时,才重新查询。`auto_transition: false` 只控制是否调用下一 Skill,不改变 Guard 已更新的 phase;`NEXT: manual` 时按 HINT 提示用户并结束本次调用,不追加确认。
|
|
77
|
+
|
|
78
|
+
先核对已有批准、委托授权和用户要求的确认方式;需要新决定时,等待明确答复后再继续。首次需要向用户澄清或确认时,必须先读取 `comet-classic/reference/decision-point.md`,按其中的选项式提问、推荐理由、每项影响和 `AskUserQuestion` 优先规则执行;已在当前上下文中时直接复用。以下事项按该协议核对授权;已有授权仍覆盖时继续,需要新决定时才提问:
|
|
79
|
+
|
|
80
|
+
- 目标 change、PRD 拆分与工作区隔离仍需要用户选择时,把相关问题放在一起询问,并等待选择。
|
|
81
|
+
- Open 产物完成后,请用户最终确认名称、范围和产物;Design 形成方案后,请用户确认正式设计。两者都按已有授权核对当前内容;需要用户决定时,提供可检查的结果并等待答复。
|
|
82
|
+
- Build 写计划前,只有执行/TDD/review 配置缺失或用户要求更改时,才请用户补充或修改;用户主动要求 `plan-ready` 暂停后,等明确继续指令再恢复。
|
|
83
|
+
- Verify 中需要接受偏差、处理实现与 Spec 不一致的问题,或达到自动修复上限后决定如何继续;Archive 中需要选择归档与交付方式。
|
|
84
|
+
- 需要从预设升级为完整流程,或 Build 中需要扩大范围、重新设计、拆分 change。
|
|
85
|
+
|
|
86
|
+
用户明确选择前,不写入依赖该决定的状态,不执行对应分支操作,也不绕过阶段 Guard。已有仍有效的授权与配置直接复用;对于范围内原因明确且可以修复的问题、能根据证据补齐的状态,以及其他只有一种合法做法的步骤,自动继续,不额外询问“是否继续”。
|
|
87
|
+
|
|
88
|
+
归档与交付方式合并为同一个最终确认,由 `/comet-archive` 核对用户授权、Git 的实际状态,以及所选交付操作是否完成。验证通过不代表归档授权;归档目录存在也不代表提交、push 或 PR 已完成。
|
|
89
|
+
|
|
90
|
+
## 每个阶段都必须遵守的规则
|
|
91
|
+
|
|
92
|
+
- 流程状态以 Runtime 返回的 phase、Guard 检查结果和当前工作区绑定为准;文件与对话用于核对,不能据此手改 phase,绕过确认或验证。
|
|
93
|
+
- proposal 记录目标与范围,spec 规定行为和验收要求,design_doc 指向唯一一份正式技术设计,plan 说明实施方法,tasks.md 记录任务完成状态。
|
|
94
|
+
- 遵循已确认的执行方式、TDD 和 review 配置;autonomous 仍须完成 full 要求的设计、计划、实际验证和独立审查。配置缺失或用户要求更改时由 Build 确认,不能根据模型名称擅自替换。
|
|
95
|
+
- 未提交改动先按 `comet-classic/reference/dirty-worktree.md` 核对来源和归属;只处理当前 change,保护无关改动。状态更新被拒绝、路径越界、依赖不可用或归属不明时,读取 `comet-classic/reference/context-recovery.md` 的“入口错误与恢复”,报告原错误并执行对应恢复规则。
|
|
96
|
+
- 当前阶段发生异常时读取 `comet-classic/reference/debug-gate.md`,先调查再修复;只有实际运行过测试或构建,才能声称完成相应检查。以前通过的结果,只有在 Runtime 确认仍有效时才能复用。
|
|
97
|
+
|
|
98
|
+
需要状态字段含义时读 `comet-classic/reference/comet-yaml-fields.md`;需要产物目录说明时读 `comet-classic/reference/file-structure.md`。其余参考只在上方触发条件满足时读取。
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# 自动衔接下一阶段协议
|
|
2
|
+
|
|
3
|
+
进入新阶段或交给新 Agent 时,把当前 continuation 与 `contextRequest` 一并交给接收方,按 [任务上下文协议](scripts.md#任务上下文与产物语言) 获取一次快照。`wait` 先区分等待原因,同一阶段连续命令不重复获取。
|
|
4
|
+
|
|
5
|
+
规范路径:`comet-classic/reference/auto-transition.md`
|
|
6
|
+
|
|
7
|
+
本协议由所有 comet 子 skill 共享,定义阶段守卫推进后的自动衔接规则。
|
|
8
|
+
|
|
9
|
+
## 术语区分
|
|
10
|
+
|
|
11
|
+
guard `--apply` 检查通过后,会更新 `.comet.yaml` 的 `phase` 字段,进入下一阶段。无论 `auto_transition` 如何设置,这一步**都会执行**。`auto_transition` 只决定更新阶段后,**是否自动调用下一个 Skill**。
|
|
12
|
+
|
|
13
|
+
## 执行方式
|
|
14
|
+
|
|
15
|
+
`mode: wait` 且 `waitReason: manual-transition` 表示只停止自动加载下一个 Skill:展示返回的 Skill 入口并交还控制权;用户已明确调用当前 Skill 时,执行它的当前工作及完成命令,随后仍遵守手动衔接。`waitReason: executor` 或 Action 为 `running` 时,才等待原执行者,不重新派发。旧响应没有等待原因时,依据 Action 是否已领取以及 `automatic: false` 区分,不能把无人领取的 pending Action 当作运行中任务。
|
|
16
|
+
|
|
17
|
+
SDK 响应带有 `agent.continuation.mode` 时,先按该字段处理:`execute` 执行返回的命令或加载明确指定的 Skill;`wait` 按上述等待原因处理;`ask` 按决策协议核对已有授权,只有需要新决定时才展示提案并等待答复;`reconcile` 核对原执行结果或处理列出的阻塞;`done` 结束。`mode` 优先于兼容字段 `nextAction.kind`;例如旧 `kind: reconcile` 对应的新 `mode: wait` 仍应等待原任务。只有 `invoke_skill` 才加载 Skill,不能把工具的 `ref` 当成 Skill 名称;先完成 Skill 要求的真实工作,再按 `completion` 填写并执行提交命令。`currentRef` 指向同一响应中的当前工作,直接读取该字段,不额外调用命令。`inputSummary` 只保留当前工作的上下文,不替代原 Action 输入或 Runtime 证据;只有确需摘要未包含的内容时,才使用返回的详情命令。直接复用当前动作的输入、请求模板、Run 身份、revision 和工作目录;占位值填写真实输入,不能作为批准。写入后使用新响应,不因阶段切换重新查询。响应没有 `mode` 时沿用下方规则。
|
|
18
|
+
|
|
19
|
+
退出条件满足且阶段守卫更新 phase 后,优先按本次成功 JSON 结果中的 `agent.continuation` 继续:`automatic: true` 时调用 `skill` 指定的 Skill;false 时提示用户手动运行该 Skill,并结束本次调用。下一阶段可直接使用这里返回的状态信息,不重复 next、select 或 check。只有恢复会话、外部状态或工作区发生变化,或者旧结果没有这些信息时,才运行:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
comet state next <change-name>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
脚本根据 `phase`、`workflow`、`auto_transition` 确定并返回下一步:
|
|
26
|
+
|
|
27
|
+
- `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
|
|
28
|
+
- `NEXT: manual` → 不要调用下一 skill,按 `HINT` 提示用户手动运行 `/<SKILL>`
|
|
29
|
+
- `NEXT: done` → 流程已完成,无需继续
|
|
30
|
+
- `NEXT: delivery` → change 已归档,按 delivery 摘要完成收尾,不再推进阶段
|
|
31
|
+
|
|
32
|
+
## 预设路由
|
|
33
|
+
|
|
34
|
+
`workflow: hotfix` 时,`phase: build` 返回 `comet-hotfix`;`workflow: tweak` 时返回 `comet-tweak`。其余 phase(`verify`、`archive`)按标准 Skill 名称返回(`comet-verify`、`comet-archive`),不受 workflow 类型影响。预设 Skill 内部的"连续执行模式"可能覆盖 `auto_transition` 行为——详见对应预设的 `<IMPORTANT>` 块。
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Classic 产物布局协议
|
|
2
|
+
|
|
3
|
+
进入已选 change 的阶段时,使用本轮 `comet state check <change-name> <phase> --json` 返回的 layout;无需再单独查询布局。尚未选择 change、入口未提供 layout,或只处理根目录迁移时,才在项目根运行:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
comet classic root show
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
只接受 `schema: comet.classic-layout.v1`。把 layout 的 `openSpecRoot`、`changesRoot`、`archiveRoot`、`specsRoot`、`superpowersRoot` 分别作为 `<classic-open-spec-root>`、`<classic-changes-root>`、`<classic-archive-root>`、`<classic-specs-root>`、`<classic-superpowers-root>` 对应的实际目录。`<classic-change-dir>` 使用入口返回的 changeDir;只有尚未创建 change 时,才用 changesRoot 与 name 拼出路径。对于已归档的 change,不要使用未归档 change 的目录规则拼接路径。本轮路径以返回的 layout 为准;恢复会话时若缺少上下文,或工作区发生变化,应重新查询,不沿用旧目录信息。
|
|
10
|
+
|
|
11
|
+
## 命令规则
|
|
12
|
+
|
|
13
|
+
- 本 Skill 及其他 Comet 自有的 Classic Skill 调用官方 OpenSpec CLI 时,必须使用以下适配命令:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
comet classic openspec -- <args...>
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- 适配器会在配置的 OpenSpec 根目录中运行官方 CLI,并原样返回 stdout、stderr 和退出码。不得为同一仓库另行注册或查询 OpenSpec store。
|
|
20
|
+
- 需要取得可以直接执行的下一条命令时,使用 `comet classic openspec --agent-json -- <args...>`。读取 `data.upstream.data` 中的 OpenSpec JSON,并保留 `data.upstream.cwd/stdout/stderr/exitCode` 用于排错。执行 `data.nextAction` 时,完整使用它提供的 argv 和 cwd。原始 nextSteps 假设命令在 OpenSpec 根目录中执行,不能直接搬到项目根运行。未使用 `--agent-json` 的普通调用仍原样返回 OpenSpec 输出。
|
|
21
|
+
- 只有用户明确要求在解析得到的 OpenSpec 根目录中直接使用官方 CLI 时,才可直接运行 `openspec`。
|
|
22
|
+
|
|
23
|
+
## 路径规则
|
|
24
|
+
|
|
25
|
+
- 绝对路径只用于文件读写。`data.artifactRefs` 提供相对仓库根目录的路径:`change`、`tasks`、`designDoc`、`plan`、`plansRoot`、`handoffContext`。将 `change` 作为 `<classic-change-ref>`,`tasks` 作为 `<classic-task-authority-ref>`;状态中的路径字段和计划的 `comet-task-authority` 必须使用这些相对路径,不传绝对路径 `<classic-change-dir>`。新 plan 的相对路径由 `plansRoot` 与文件名组成;读写文件时,再通过 `projectRoot` 解析出完整路径。自定义路径也必须以项目根为基准,不得包含 `..`、跨项目链接,或指向另一 change 的任务清单。
|
|
26
|
+
- change、tasks、delta spec、handoff 和 archive 等文件路径必须使用上方确定的 `<classic-*>` 逻辑路径;例如 tasks 使用 `<classic-change-dir>/tasks.md`。不要仅把固定目录改写成逻辑路径的名称,实际读写仍使用写死的目录。
|
|
27
|
+
- Superpowers 文件使用 `<classic-superpowers-root>/...`,不要从 OpenSpec root 或当前 cwd 推导。
|
|
28
|
+
- `comet state`、`comet guard`、`comet handoff`、`comet archive` 会自行解析布局;不得把物理 root 写入 `.comet/current-change.json`。
|
|
29
|
+
- 若 root show 或任一写命令报告 legacy/docs 两套根目录冲突、配置无效或迁移未完成,立即停止写入,运行只读的 `comet doctor` 检查。不要自行扫描两个根目录后猜测 change 归属,也不要向两处同时写入。
|
|
30
|
+
|
|
31
|
+
## 新旧项目与迁移
|
|
32
|
+
|
|
33
|
+
- 新 Classic 项目默认使用 `docs/openspec/`。
|
|
34
|
+
- 为兼容旧项目,缺少 `classic.artifact_layout` 时使用项目根下的 `openspec/`(legacy);新项目 init 会明确写入 docs。`comet update` 检测到已有 `openspec/` 产物时,会把配置补为 `legacy`,不会移动产物。
|
|
35
|
+
- 普通 init/update 不移动旧产物。先运行 `comet classic root move docs --dry-run` 查看现状;用户确认后,再运行 `comet classic root move docs --apply` 迁移。Runtime 负责记录迁移标识,并在持有锁时再次检查迁移条件。
|
|
36
|
+
- 迁移会原样移动旧布局下的完整目录,包括 active、unmanaged 和尚未完成归档的 change;这些 change 的状态不会阻止根目录迁移。
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Classic 状态文件字段说明
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/comet-yaml-fields.md`
|
|
4
|
+
|
|
5
|
+
本文件说明每个 change 的状态字段:SDK 新 change 使用 `comet-state.yaml`,历史 `.comet.yaml` 原地兼容,compat 初始化仍用旧名;两种文件共存时(包括其中一个是失效符号链接)停止并核对来源,文件位于 `<classic-change-dir>/`。该目录按 `comet-classic/reference/classic-layout.md` 解析。需要了解字段时再查阅,不随 Skill 一次性加载。项目默认配置位于 `.comet/config.yaml`,全局默认配置位于 `~/.comet/config.yaml`;项目配置优先于全局配置。
|
|
6
|
+
|
|
7
|
+
## 示例
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
workflow: full
|
|
11
|
+
language: zh-CN
|
|
12
|
+
phase: build
|
|
13
|
+
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
|
|
14
|
+
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
|
|
15
|
+
base_ref: a1b2c3d4e5f6...
|
|
16
|
+
build_mode: subagent-driven-development
|
|
17
|
+
build_pause: null
|
|
18
|
+
subagent_dispatch: confirmed
|
|
19
|
+
tdd_mode: tdd
|
|
20
|
+
review_mode: standard
|
|
21
|
+
auto_transition: true
|
|
22
|
+
isolation: branch
|
|
23
|
+
bound_branch: null
|
|
24
|
+
verify_mode: light
|
|
25
|
+
verify_result: pending
|
|
26
|
+
verify_failures: 0
|
|
27
|
+
verification_report: null
|
|
28
|
+
branch_status: pending
|
|
29
|
+
created_at: 2026-05-26
|
|
30
|
+
verified_at: null
|
|
31
|
+
archive_confirmation: null
|
|
32
|
+
archived: false
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 必需字段
|
|
36
|
+
|
|
37
|
+
| 字段 | 含义 |
|
|
38
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
39
|
+
| `workflow` | `full`、`hotfix` 或 `tweak` |
|
|
40
|
+
| `language` | 产物语言,仅支持 `en` 或 `zh-CN`。`comet init` 根据安装范围,将 `classic.language` 写入项目或全局 `.comet/config.yaml`。创建 change 时,优先采用项目配置,没有时再用全局配置,并把选定值保存到实际状态文件,作为 OpenSpec / Superpowers 产物的主要语言 |
|
|
41
|
+
| `phase` | 当前阶段:`open`、`design`、`build`、`verify`、`archive`(init 统一设为 `open`,guard 负责过渡) |
|
|
42
|
+
| `design_doc` | 关联的 Superpowers Design Doc 路径,可为空 |
|
|
43
|
+
| `plan` | 关联的 Superpowers Plan 路径,可为空 |
|
|
44
|
+
| `base_ref` | init 时记录的 git commit SHA,用于 scale 评估。无 plan 时作为改动文件数统计基准 |
|
|
45
|
+
| `build_mode` | 已选择的执行方式,可为空。`autonomous`:由用户明确选择后,自主规划和执行,可以把范围明确的一组任务交给子代理,不强制加载外部规划/执行 Skill;`subagent-driven-development`:主会话协调,后台子代理负责实现;`executing-plans`:主会话按计划顺序执行;`direct`:默认仅适用于 hotfix/tweak,full 需要 direct_override。写计划前确认执行方式,不根据模型名称擅自替换旧配置 |
|
|
46
|
+
| `build_pause` | build 阶段的暂停状态。`null` 表示未暂停;`plan-ready` 表示计划已生成,且用户明确要求计划后暂停(包括切换模型)。收到继续指令后沿用有效计划与配置,不因这个暂停状态而重新询问配置 |
|
|
47
|
+
| `subagent_dispatch` | `null` 或 `confirmed`。`confirmed` 记录用户已选择 `subagent-driven-development`;该模式只有带此记录时才能离开 build 阶段 |
|
|
48
|
+
| `tdd_mode` | `tdd` 或 `direct`。full workflow 离开 build 阶段前必须已选择。`tdd` 强制每个任务先写失败测试再实现;`direct` 不强制逐任务 TDD,但仍需相关测试与 bug 回归证据。hotfix/tweak 默认 `direct` |
|
|
49
|
+
| `review_mode` | `off`、`standard` 或 `thorough`。full workflow 离开 build 阶段前必须已选择;hotfix/tweak 默认 `off` |
|
|
50
|
+
| `isolation` | `current`、`branch` 或 `worktree`。full change 在 Open 阶段创建产物前决定工作区;hotfix/tweak 在入口决策点后也可如实使用三种模式,不得在未创建分支时虚构为 `branch` |
|
|
51
|
+
| `bound_branch` | 工作区绑定的分支,可为空。首次设置 `isolation: current` / `branch` / `worktree` 或执行入口检查时,记录命令所在目录的当前 Git 分支。worktree 模式下,必须在对应工作区内执行 set/check/guard,否则会绑定或比较错误的分支。切换 `isolation` 模式会重新绑定当前分支;重复设置同一模式则保留原绑定。后续 `comet state select` / `comet state check` 会核对当前分支是否与绑定一致;不一致时 select 拒绝执行,检查返回 `BLOCKED`。此时按决策点协议,请用户选择切回绑定分支,或在明确确认后运行 `comet state rebind <change-name>`。清空 `isolation` 时也会清空本字段 |
|
|
52
|
+
| `verify_mode` | `light` 或 `full`,可为空 |
|
|
53
|
+
| `auto_transition` | `true` 或 `false`。只控制阶段守卫推进 phase 后是否自动调用下一个 skill;`false` 时由 `comet state next` 输出 `manual`,暂停下一 skill 调用,但不阻止 phase 字段更新 |
|
|
54
|
+
| `verify_result` | `pending`、`pass` 或 `fail` |
|
|
55
|
+
| `verify_failures` | 由 Runtime 维护的连续验证失败次数。`verify-fail` 自动加一;`verify-pass` 或 `archive-reopen` 重置为 `0`。已经失败 `3` 次后,如果再次失败,必须请用户决定如何继续 |
|
|
56
|
+
| `verification_report` | 验证报告文件路径,verify 通过前必须指向已存在文件 |
|
|
57
|
+
| `branch_status` | `pending` 或 `handled`。Verify 阶段保持 pending;归档时的 handled 只用于兼容旧状态,不能据此认定用户已授权 local/push/pr 或相应操作已成功。实际授权由 state delivery 保存;Runtime 确认所选本地或远端操作全部完成后,才清除当前 change 的选择 |
|
|
58
|
+
| `created_at` | change 创建日期(init 时自动写入),格式 `YYYY-MM-DD` |
|
|
59
|
+
| `verified_at` | 验证通过时间,可为空 |
|
|
60
|
+
| `archive_confirmation` | `null`、`pending` 或 `confirmed`。verify-pass 进入 archive 时设为 pending。用户明确选择归档,并选定仅本地保存、push 或 PR 的交付方式后,通过 archive-confirm 设为 confirmed。archive-reopen 会清除确认,并使旧 delivery 授权失效;重新验证后需要再次确认 |
|
|
61
|
+
| `archived` | change 是否已归档 |
|
|
62
|
+
|
|
63
|
+
## 可选字段
|
|
64
|
+
|
|
65
|
+
| 字段 | 含义 |
|
|
66
|
+
| ----------------- | -------------------------------------------------------------------------------- |
|
|
67
|
+
| `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`,必须显式设为 `true` |
|
|
68
|
+
|
|
69
|
+
## 状态更新规则
|
|
70
|
+
|
|
71
|
+
- `build → verify` 前,`isolation` 必须是 `current`、`branch` 或 `worktree`
|
|
72
|
+
- `build → verify` 前,`build_mode` 必须已选择
|
|
73
|
+
- `build_mode: subagent-driven-development` 必须同时有 `subagent_dispatch: confirmed`
|
|
74
|
+
- full 采用 `build_mode: autonomous` 时,design_doc、plan、isolation、tdd_mode 仍须有效,并须选择 standard/thorough 独立审查;这不等于开启 direct_override,也不改变已有执行方式
|
|
75
|
+
- full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`
|
|
76
|
+
- full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`
|
|
77
|
+
- `build_mode: direct` 默认只允许 `hotfix` / `tweak`;full workflow 需要 `direct_override: true`
|
|
78
|
+
- `build_pause` 不是执行方式,不得写入 `build_mode`
|
|
79
|
+
- 协调与交付记录通过 `state checkpoint` / `state delivery` 管理,不把其中的 JSON 字段直接写入实际状态文件;读取和恢复方式见 context-recovery.md 与 comet-archive
|
|
80
|
+
- 这些约束同时存在于 `comet guard <name> build --apply` 和 `comet state transition <name> build-complete`
|
|
81
|
+
- `archive_confirmation` 由 Runtime 管理,只能通过 `verify-pass`、`archive-confirm` 和 `archive-reopen` 状态机事件更新,不能用 `set` 直接伪造确认;`archived` 事件和实际归档命令都要求它的值为 `confirmed`
|
|
82
|
+
- `preset-escalate` 事件:仅允许 `hotfix`/`tweak` workflow 在 `phase: build` 时调用。它会原子更新 `workflow`/`classic_profile` 为 `full`,将 `phase` 回退到 `design`,并清空 `design_doc`,以满足 comet-design 的入口要求。这是预设升级到 full 的唯一合法方式。直接 `set phase design` 会被状态机拒绝;classic_profile 由 Runtime 管理,不能通过 `set classic_profile` 手动更改
|