comet-dsh-plugin 0.0.0-stage → 0.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/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 +57 -4
- package/rules/comet-workflow-guard.md +63 -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 +294 -0
- package/skills/comet/scripts/comet-hook-router-guard.mjs +628 -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 +571 -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 +464 -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,144 @@
|
|
|
1
|
+
# 稳定公开 CLI 协议
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/scripts.md`
|
|
4
|
+
|
|
5
|
+
Classic Skill 调用 Comet Runtime 的方式以本文件为准。Skill 只使用 PATH 中的公开 `comet` CLI;随包发布的 `comet/scripts/*.mjs` 是安装过程和 Runtime 使用的内部文件,Skill 不应搜索或直接调用它们。
|
|
6
|
+
|
|
7
|
+
## CLI 引导
|
|
8
|
+
|
|
9
|
+
进入工作流时,直接运行下方需要的公开 `comet` 命令。若返回 `command not found`、`executable not found` 或 `ENOENT`,停止并说明 Comet CLI 安装不完整;不得通过搜索 Skill 文件、遍历平台目录或调用内部 bundle 绕过该问题。CLI 已启动但返回非零退出码时,报告原错误,不得改用内部脚本重试。
|
|
10
|
+
|
|
11
|
+
## 公开工作流协议
|
|
12
|
+
|
|
13
|
+
日常工作流统一调用公开 CLI:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
comet classic workspace prepare <change-name> --isolation <current|branch|worktree> --json
|
|
17
|
+
comet classic workspace resolve <change-name> --json
|
|
18
|
+
comet state select <change-name>
|
|
19
|
+
comet state current
|
|
20
|
+
comet state clear-selection
|
|
21
|
+
comet state check <change-name> <phase> --json
|
|
22
|
+
comet state check <change-name> <phase> --recover --json
|
|
23
|
+
comet state check <change-name> <phase> --recover --details --json
|
|
24
|
+
comet state checkpoint <change-name>
|
|
25
|
+
comet state checkpoint <change-name> --file <json-path>
|
|
26
|
+
comet state sync-plan <change-name>
|
|
27
|
+
comet state delivery <change-name>
|
|
28
|
+
comet state delivery <change-name> --verify
|
|
29
|
+
comet state delivery <change-name> --file <json-path>
|
|
30
|
+
comet state complete-build <change-name> --checks <checks-json-file>
|
|
31
|
+
comet guard <change-name> verify --report <report-ref> --apply --checks <checks-json-file>
|
|
32
|
+
# Compat:平台执行后记录实际结果,不执行 command 文本。
|
|
33
|
+
comet state record-check <change-name> <build|verify> --command "<实际命令>" --exit-code <实际退出码>
|
|
34
|
+
comet guard <change-name> <phase> --apply
|
|
35
|
+
comet handoff <change-name> design --write
|
|
36
|
+
comet archive <change-name>
|
|
37
|
+
comet resume-probe . --stdin --json
|
|
38
|
+
comet classic intent route --stdin
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
在 Open 阶段先运行 workspace prepare。工作区未知、发生切换或之前的选择已失效时,运行 workspace resolve,进入返回的 projectRoot 后再执行 select。正常进入下一阶段时,沿用仍有效的选择,不重复扫描 Worktree;源码写入应属于当前选定的 change。
|
|
42
|
+
|
|
43
|
+
入口 check --json 会返回 layout、configuration、nextAction、任务摘要、coordination 和 delivery;已经返回的字段不再单独查询。恢复会话时若缺少上下文,先用 --recover 取得恢复摘要;需要全部任务、检查点或证据时才加 --details,具体见 context-recovery.md。
|
|
44
|
+
|
|
45
|
+
只执行当前动作仍缺少的查询。把多条 `comet` 命令放进同一次 shell 调用只减少工具往返,每条 CLI 仍各自启动;要减少重复调用,应复用响应已有字段。存在先后依赖时,上一条成功后再执行下一条,并检查每条退出码;不能用最后一条成功掩盖前面的失败。
|
|
46
|
+
|
|
47
|
+
任务读取、稳定 ID、勾选和 checkpoint 支持 SDK 与 Compat;它们不推进 SDK Run,不代替检查、阶段批准或 complete-build。任务完成状态始终以同一 tasks.md 为准。SDK 沿用当前 Run 继续,记录协调进度后无需为了查下一步再查询。
|
|
48
|
+
|
|
49
|
+
checkpoint 输入必须包含 schemaVersion:1,以及 taskIds/stage/sessionId/evidence/unresolved/reviewRounds;读取时返回 `{checkpoint, stale}`。Runtime 检查数据后生成 Markdown,JSON 示例见 context-recovery.md。task-complete 会自动同步旧计划中已经建立 comet-task ID 对应关系的任务。需要单独同步时使用 sync-plan;返回 planSync mapping-required 时,只需补齐对应关系,不应重新实施任务。
|
|
50
|
+
|
|
51
|
+
delivery 输入包含 action(local|push|pr)、targetBranch,以及可选的 remote、commit、prUrl,示例见 comet-archive。普通入口和 delivery 读取不会访问网络;只有 `state delivery <change-name> --verify` 会只读核对远端和 PR 状态,并返回 `{delivery, verification}`。记录写入成功不等于交付成功。命令不可用、操作被拒绝或记录不一致时停止,不能手改内部状态来绕过检查。
|
|
52
|
+
|
|
53
|
+
guard 的 `--apply` 在检查通过后更新状态。需要直接触发状态机事件时,使用 `comet state transition`。阶段更新后,按 auto-transition.md 读取成功结果中的 `agent.continuation` 并继续;返回的状态信息缺失或失效时,才查询 next。
|
|
54
|
+
|
|
55
|
+
## 自动状态更新
|
|
56
|
+
|
|
57
|
+
guard 支持 `--apply` 参数,验证通过后自动更新实际状态文件中的字段:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
comet guard <change-name> <phase> --apply
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`--apply` 内部调用状态机的 transition。需要直接触发状态机事件时使用:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
comet state transition <change-name> open-complete
|
|
67
|
+
comet state transition <change-name> design-complete
|
|
68
|
+
comet state transition <change-name> build-complete
|
|
69
|
+
comet state transition <change-name> verify-pass
|
|
70
|
+
comet state transition <change-name> verify-fail
|
|
71
|
+
comet state transition <change-name> archive-confirm
|
|
72
|
+
comet state transition <change-name> archive-reopen
|
|
73
|
+
comet state transition <change-name> archived
|
|
74
|
+
comet state transition <change-name> preset-escalate
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
归档由 `comet archive <change-name>` 完成。OpenSpec 先把 change 移到带日期前缀的归档目录,再由 Comet 记录状态。归档前的确认状态通过 `archive-confirm` 或 `archive-reopen` 更新;不要在归档流程之外手动执行 `archived` transition。
|
|
78
|
+
|
|
79
|
+
## 检查命令与结果复用
|
|
80
|
+
|
|
81
|
+
按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 Guard 和状态查询不启动构建或测试。
|
|
82
|
+
|
|
83
|
+
## 解析下一步
|
|
84
|
+
|
|
85
|
+
阶段守卫更新 phase 后,按 auto-transition.md 优先使用成功 JSON 中的 `agent.continuation`。下一阶段可以直接使用这里返回的状态信息,不重复 next、select 或 check。只有恢复会话时缺少上下文、发生外部变化,或旧结果缺少这些信息时,才运行:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
comet state next <change-name>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
普通 `state next` 只读取下一步。返回 `comet state next <change-name> --continue --json` 时,沿原 Run 提交已接受材料并连续处理已批准的内部业务步骤。需要 Agent 工作、用户决定、失败或结果未明时返回当前下一步,不执行普通检查命令。
|
|
92
|
+
|
|
93
|
+
输出包含 `NEXT: auto|manual|done|delivery`、`SKILL: <skill-name>`(`done` 时省略),以及 `HINT`(仅 `manual` 时)。`auto_transition: false` 时输出 `manual`,表示不自动调用下一 Skill,不影响已经更新的 phase;`delivery` 表示 change 已归档,按 delivery 摘要完成收尾,不再推进阶段。
|
|
94
|
+
|
|
95
|
+
## 归档脚本
|
|
96
|
+
|
|
97
|
+
一键完成归档全部步骤:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
comet archive <change-name>
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## 阶段共用入口
|
|
104
|
+
|
|
105
|
+
收到入口返回的 layout 后,按 [产物布局](classic-layout.md) 绑定 `<classic-*>` 逻辑根;本会话已加载且绑定仍有效时直接复用。OpenSpec CLI 使用 Comet 适配器,文件路径使用这些逻辑根,无需额外运行 root show。
|
|
106
|
+
|
|
107
|
+
编辑后需要判断影响,或 continuation 指向内容判断时,读取并执行[编辑后续行](../../comet/reference/edit-review.md)。由当前 Agent 在原 Run 合并处理变化,保留有效批准和检查,只补受影响证据。各阶段的用户确认、实施方法、TDD、审查和固定应用要求仍按当前阶段正文执行。
|
|
108
|
+
|
|
109
|
+
## 任务上下文与产物语言
|
|
110
|
+
|
|
111
|
+
任务结束先按[任务学习收尾](../../comet/reference/task-learning.md)检查是否有可提交内容。有个人观察、项目经验、待评审动作或实际使用反馈时,优先用 `comet task --complete --learning-file <file>` 一次提交;没有这些内容时不创建空学习文件,用实际检查结果完成收尾。本节后面的分步命令供即时保存、单项纠正及旧版兼容;采用学习文件时无需重复执行。
|
|
112
|
+
|
|
113
|
+
所有 OpenSpec 和 Superpowers 产物都必须使用 Comet 配置的产物语言,配置值为规范化语言 ID:`en` 或 `zh-CN`。已有 change 优先使用本次有效入口返回的 `configuration.language`;仅入口未提供该字段时,才通过 `comet state get <name> language` 读取实际状态文件中的 `language`。新旧两种状态文件均不存在时,依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`;两处都没有配置时,才使用当前用户请求的语言。调用外部 OpenSpec/Superpowers Skill 时,必须把最终确定的语言明确写入提示词或 ARGUMENTS。
|
|
114
|
+
|
|
115
|
+
领取响应含 `data.contextDelivery` 时,读取 `data.context[].text` 后直接工作,不重复执行 `contextRequest`。需要正文、恢复或提交学习时分别使用 `data.contextActions.expand`、`restore`、`complete`;新 Agent 使用自己的会话标识。空结果或获取失败不阻断任务。
|
|
116
|
+
|
|
117
|
+
没有自动交付时,按当前 `agent.continuation.contextRequest` 获取任务上下文;SDK 已领取 Action 时优先使用该 Action 的 `contextRequest`。同一会话已有可核对的交付记录且正文仍在上下文中时,阶段切换沿用同一 session,以 `--context-mode incremental` 获取新增适用内容;阶段专用规则仍须加载。新 Agent、上下文压缩或恢复、记录不完整时使用 snapshot 完整交付。本协议适用于 full、hotfix、tweak、SDK、Compat 及独立阶段入口。普通状态查询、等待原任务和同阶段连续执行不重复获取。
|
|
118
|
+
|
|
119
|
+
没有请求描述时,绑定实际工作区并读取当前 `phase`,运行 `comet task <project-root> --task "<用户原始请求>" --phase "<phase>" --session "<接收方稳定会话标识>" --context-mode snapshot --json`。原始请求缺失时从当前 proposal、specs 和任务范围恢复目标。阶段切换沿用当前 Agent 的会话标识;换 Agent 时使用接收方自己的标识,不能复用派发者或已领取 Action 的其他执行者标识。同一 Agent 恢复时沿用原标识并获取 snapshot,避免已交付记录阻止内容重新进入上下文。
|
|
120
|
+
|
|
121
|
+
将 `context[].text` 加入上下文。Context Manifest(`manifest` / `<context_manifest>`)只包含摘要、选用原因和稳定 ID;需要正文、来源或验证方式时,用同一请求增加 `--expand-context "<id>"`。同一阶段连续执行中路径或操作变化时,沿用同一 `--session`,传新的 `--path`、`--operation`,使用 `--context-mode incremental` 获取新增内容。不要因每次状态响应仍带 `contextRequest` 就重复检索。空结果或获取失败时按已有明确指令继续,不循环重试。
|
|
122
|
+
|
|
123
|
+
派发实现、审查或其他子任务时,交付当前阶段、任务范围、实际工作区、有效配置、适用偏好与项目约束,并附上此上下文请求。接收方用自己的会话标识执行一次;只有隔离的独立验收阶段才使用 `verify`,Build 内审查仍使用 `build`。子任务边界限制优先,不能因继承偏好扩大写入范围或省略独立审查。
|
|
124
|
+
|
|
125
|
+
偏好中要求特定 Skill 时,按当前平台实际可用能力加载,并明确所需方法。与已确认的执行方式、TDD、审查配置或固定 Skill 冲突时说明具体差异;配置变更按现有确认流程处理,不静默替换或重复询问仍有效的决定。不可用或不兼容时说明原因并继续可执行部分。分别记录“偏好已交付”“Skill 已加载”“方法已执行”,不将检索成功当作执行成功。记忆内容不写入 `handoff_context`、`handoff_hash` 或其他批准、验收记录;记忆变化本身不触发回滚,也不能代替 Runtime 检查、用户授权和必需审查。
|
|
126
|
+
|
|
127
|
+
若 `<active_policies>` 中包含 `<verification command="...">`,将这些命令加入当前 Verify 的检查并记录实际结果。只有命令成功执行过,对应策略才能设为强制执行。
|
|
128
|
+
|
|
129
|
+
用户明确要求长期记住偏好或项目约定时,调用 `comet memory remember ... --scope global|project`。用户明确限定适用阶段时,添加可重复的 `--phase`,例如 `--phase build --phase verify`;修改已有记录用 `comet memory correct <project-root> --id <id> --phase build --phase verify --json`。只保存明确的阶段条件,不自行扩展适用范围。用户没有明确要求、但协作方式稳定且可跨任务复用时,才调用 `comet memory observe --text "<偏好内容>" --workflow <classic|native> --change <change-id> --candidate-key <change-id>-<行为短名>`(三个选项均为必需;`--candidate-key` 用 change ID 加行为短名生成稳定标识)。两者都不得保存任务摘要、进展、命令输出或测试结果。
|
|
130
|
+
|
|
131
|
+
项目记忆与个人记忆独立保存。任务结束前,把本次验证过且未来任务仍可复用的经验写入项目记忆:`comet knowledge remember <project-root> --title "<简明标题>" --text "<现象、做法、验证结果>" --type <fact|decision|pattern|procedure|constraint|failure-resolution> --workflow classic --change <change-id> --evidence "<来源文件,逗号分隔>" --json`。同一标题默认更新已有条目。`--evidence` 绑定支持结论的项目内文件;没有文件依据的协作决策可省略。采用已有经验前,追加 `--expand-context "project-memory:<slug>"` 展开并核对来源;来源变化或不可读取时先验证并更新。任务摘要、一次性命令输出和未验证的猜测不得写入。
|
|
132
|
+
|
|
133
|
+
任务结束前,Agent 独立完成项目学习检查:
|
|
134
|
+
|
|
135
|
+
1. 本次没有合格观察、可复用经验或已知待评审时,直接声明 `no-observation`;不调用 review,不创建空动作文件。只有当前完成响应或已有回执提示本次 change 有待评审时,运行 `comet knowledge review <project-root> --workflow classic --change <change-id> --json`。
|
|
136
|
+
2. 有待评审时,根据返回的 `recordFields` 和来源证据编写动作文件,用 `--id <id> --file <actions.json>` 提交;真实评审没有可复用结论时可提交 `[]`。用户无需编写 JSON。核对 `submission.status` 为 `applied`;`accepted` 只表示已接收。只处理本次 change,后续完成响应新出现的待评审仍按该规则处理。
|
|
137
|
+
3. 保存本次项目记忆后,在完成命令中传 `--project-learning-check submitted --memory <返回的 slug>`;多个回执用逗号分隔。无可复用经验时传 `no-observation`,未检查时传 `not-run`。
|
|
138
|
+
4. 完成响应的 `projectLearning.submissionVerified` 为 `true`,`pendingHostReviewCount` 和 `pendingReflectionCount` 都为 `0`,才报告项目学习检查完成;否则按 `nextActions` 处理并说明未完成项。学习失败不阻断已完成的开发任务。
|
|
139
|
+
|
|
140
|
+
每次任务结束前完成一次学习检查:有明确后续复用条件的用户纠正、偏好或协作习惯先调用 `comet memory observe`,再在完成命令中传 `--learning-check submitted`;确认没有合格观察时传 `--learning-check no-observation`,没有执行检查时传 `--learning-check not-run`。首次观察只形成 `trial` 候选,来自不同 change 的第二次独立成功观察才可能晋级。观察 JSON 的 `learning.result` 和 `status.learning.lastCheck` 是诊断依据。
|
|
141
|
+
|
|
142
|
+
实际使用某条内容并已得知结果后,使用返回的 `applications[].applicationId`(Hook 文本中的 `application_id`)运行 `comet task <project-root> --task "<用户原始请求>" --application "<application-id>" --outcome used-successfully|ignored|overridden|corrected|contributed-to-failure --json`,如实记录使用结果;不得把未使用的条目标为使用成功。任务结束时,运行带 `--complete --workflow classic --change <change-id> --learning-check submitted|no-observation|not-run --project-learning-check submitted|no-observation|not-run [--memory <slug>]` 的 `comet task`,分别记录个人记忆和项目学习检查。
|
|
143
|
+
|
|
144
|
+
没有 Hook 时,由 Skill 调用相同接口。`comet memory context` 只保留为兼容入口;插件未返回结果或调用失败,不会阻止工作流继续。
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Classic SDK 执行方法
|
|
2
|
+
|
|
3
|
+
按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 用户选择的方法、批准、计划和完整验收要求继续有效。
|
|
4
|
+
|
|
5
|
+
仅在 `runtimeFormat: sdk` 时读取当前阶段的章节。阶段命令、Action、Wait 和输入模板以主 Skill 与最新 continuation 为准;本参考说明实际工作和完成条件。
|
|
6
|
+
|
|
7
|
+
所有产物与外部 Skill 输入使用当前 configuration.language。每次阶段入口、接收新 Agent 和上下文恢复,先按 [任务上下文协议](scripts.md#任务上下文与产物语言) 使用当前 continuation 或已领取 Action 的 `contextRequest`;派发子任务时一并交付阶段、任务范围、实际工作区和有效配置。保留已有事实与有效证据。
|
|
8
|
+
|
|
9
|
+
## 阶段入口与恢复
|
|
10
|
+
|
|
11
|
+
复用同一 change、工作区和 Run 的最新 continuation、配置、phase、revision 与路径;只有冷恢复、外部变化、响应过期或字段缺失时,才用 `comet state next <change-name> --json` 补读。阶段入口不重复获取同一快照;写入仍由 Runtime 校验版本和证据。
|
|
12
|
+
|
|
13
|
+
SDK 新 change 使用 `comet-state.yaml`,历史 `.comet.yaml` 原地保留。两文件共存(包括失效符号链接)时停止并保留现场,不自动改名或覆盖。路径、Runtime 归属和 layout 以当前响应为准。
|
|
14
|
+
|
|
15
|
+
响应含 `agent.continuation.mode` 时按[自动衔接](auto-transition.md)执行;mode 优先于旧 `nextAction.kind`。区分手动衔接、原执行者等待与结果核对,完成实际工作后才提交 `completion`。无 mode 的旧响应才按各阶段的 kind 路由;结果未明时核对原 Action,不重发外部工作。
|
|
16
|
+
|
|
17
|
+
编辑后需要判断实际影响,或 continuation 指向内容判断时读取[编辑后续行](../../comet/reference/edit-review.md)。只读取当前阶段与实际发生的异常所需参考,不展开其余阶段。
|
|
18
|
+
|
|
19
|
+
## 开始与产物
|
|
20
|
+
|
|
21
|
+
新建 full、hotfix 或 tweak 时,先按[宿主能力核对](../../comet/reference/host-check.md)检查当前所需能力,再按 workspace.md 确定隔离方式并进入返回的 projectRoot。三种流程统一使用以下顺序:
|
|
22
|
+
|
|
23
|
+
1. 先核对当前目录、Runtime 归属和已有 OpenSpec change。已有 SDK Run 时直接恢复其当前 Action,补齐缺失产物,不再执行 OpenSpec `new change` 或 `state init`。
|
|
24
|
+
2. 真正的新 change 先创建 OpenSpec 基础目录;仅在此分支加载下面的新建 Skill。已有基础目录但初始化中断时,用 OpenSpec `status --change <name> --json` 核对实际产物,确认属于当前需求后补做初始化,保留文件。
|
|
25
|
+
3. 基础目录创建成功后,立即运行 `comet state init <name> <full|hotfix|tweak> --isolation <selected-isolation>`,再运行 `comet state select <name>`。不要先初始化 Runtime 再调用 OpenSpec `new change`,后者会拒绝已存在的目录。初始化失败时保留 OpenSpec 目录,恢复时只补未完成步骤。
|
|
26
|
+
4. SDK Run 已存在后,通过 `status` 和 `instructions` 填充当前需要的产物,再按阶段入口预览 Open 并取得用户批准。已有目录无法确认归属时先停止核对,不覆盖或新建第二份 Run。
|
|
27
|
+
|
|
28
|
+
真正的新 change 创建基础目录时:
|
|
29
|
+
|
|
30
|
+
**立即执行:** 使用 Skill 工具加载 openspec-new-change 技能。禁止跳过此步骤。
|
|
31
|
+
|
|
32
|
+
<!-- external-openspec-skill-override -->
|
|
33
|
+
|
|
34
|
+
技能加载后,通过 `comet classic openspec -- <args...>` 执行命令,使用 `<classic-*>` 路径。基础目录创建后返回上面的初始化步骤,再填充产物。hotfix 的 proposal 记录问题、根因和修复目标;tweak 记录动机、目标和范围。两者保存简短 design.md 与 tasks.md;影响已有验收时创建所需 delta spec,tweak 不因 delta spec 升级。
|
|
35
|
+
|
|
36
|
+
## Design
|
|
37
|
+
|
|
38
|
+
读取当前 proposal、tasks、delta specs 和已有设计中与本轮有关的内容;摘要被截断或缺少验收正文时补读原文。行为需求以 OpenSpec 为准,技术设计引用需求,不创建第二份规格。已确认需求不重新询问。
|
|
39
|
+
|
|
40
|
+
**立即执行:** 使用 Skill 工具加载 Superpowers brainstorming 技能。禁止跳过此步骤。
|
|
41
|
+
|
|
42
|
+
技能加载后,只采用探索与设计方法;传入当前 change、已绑定工作区、已知事实、约束和源文件引用。遇到无法推断且会改变结果的决定时,按 decision-point.md 提供问题、推荐理由、选项及影响。信息充分时直接形成方案,不设最低问答轮数;真实存在取舍时比较方案,高风险接口、迁移、安全和并发说明失败路径与验证策略。
|
|
43
|
+
|
|
44
|
+
持续保存 `brainstorm-summary.md`,区分候选与已确认内容。Spec Patch 先说明具体改动并取得用户同意,再修改 delta spec;大幅改变范围时重新澄清。需要重新确认时,按[需求变化后的重新确认](decision-point.md#需求变化后的重新确认)说明变化及影响。最终方案统一通过主 Skill 的 Design Wait 确认,仍绑定当前 Design 提案哈希;不再追加整份设计文档批准,也不让外部 Skill 自动进入规划、实施或切换工作区。
|
|
45
|
+
|
|
46
|
+
批准后完善唯一 Design Doc:已有引用优先沿用,否则使用当前 change 的 design.md;项目明确要求独立文档时,OpenSpec design.md 仅保存摘要和链接。frontmatter 仅含 `comet_change: <change-name>`、`role: technical-design`、`canonical_spec: openspec`。设计覆盖方案、取舍、风险和测试策略,正文与已批准提案一致后提交。中断后读取已保存摘要、源文件与当前 Wait,只补未完成工作。
|
|
47
|
+
|
|
48
|
+
## Build
|
|
49
|
+
|
|
50
|
+
Build 的 TDD、调试和最终检查均使用平台工具,保留可复核的结果。
|
|
51
|
+
|
|
52
|
+
已选配置要求的实施、TDD 或审查能力,按[宿主能力核对](../../comet/reference/host-check.md) 在开始实现前确认;已有仍有效的核对直接复用。
|
|
53
|
+
|
|
54
|
+
工作区沿用 Open 的绑定;需要展示、补齐或更改配置时,读取[执行配置展示](decision-point.md#执行配置展示),按当前 change 的值、含义和确认状态呈现。各字段的选择与要求如下:
|
|
55
|
+
|
|
56
|
+
| 配置 | 选择与要求 |
|
|
57
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| build_mode | autonomous 自行规划与实施;executing-plans 按固定计划实施;subagent-driven-development 由实现代理实施、主会话协调;direct 由当前会话按计划直接实施 |
|
|
59
|
+
| tdd_mode | tdd 保留真实 RED/GREEN;direct 不要求 RED/GREEN,仍做相关检查与缺陷回归 |
|
|
60
|
+
| review_mode | off 跳过自动审查;standard 审查风险任务与最终集成;thorough 做任务或分段审查及最终集成 |
|
|
61
|
+
|
|
62
|
+
full autonomous 必须采用 standard 或 thorough。full direct 需要用户明确选择并记录 `direct_override: true`,仍完成设计、计划和验证。subagent-driven-development 对应 `subagent_dispatch: confirmed`,其他方式为 null。
|
|
63
|
+
|
|
64
|
+
已有待决定 Wait 复用原提案,提案改变后按现有机制重新确认,不沿用过期批准。用户明确选择完整配置后,使用主 Skill 的 `propose-build --confirmed` 保存提案与批准;缺少决定时保留 Wait。
|
|
65
|
+
|
|
66
|
+
任务正文与完成状态以 tasks.md 为准。保留任务 ID;计划引用设计和当前任务权威,写入 `<!-- comet-task-authority: <classic-task-authority-ref> -->` 和每项 `<!-- comet-task-ref:<task-id> -->`,不复制 checkbox。计划列出任务范围、依赖、约束和验收方式;高风险部分补充理由、失败处理和回退。frontmatter 保留 `change`、`design-doc` 和实施前的 `base-ref`,恢复时不重写旧 base-ref。已有有效计划直接复用。
|
|
67
|
+
|
|
68
|
+
autonomous 直接制定计划。其他策略需要编写计划时:
|
|
69
|
+
|
|
70
|
+
**立即执行:** 使用 Skill 工具加载 writing-plans 技能。禁止跳过此步骤。
|
|
71
|
+
|
|
72
|
+
技能加载后,只采用编写与自检方法,完成后返回当前 Run。实施时,executing-plans 策略:
|
|
73
|
+
|
|
74
|
+
**立即执行:** 使用 Skill 工具加载 executing-plans 技能。禁止跳过此步骤。
|
|
75
|
+
|
|
76
|
+
技能加载后,使用当前配置与固定计划实施。subagent-driven-development 策略:
|
|
77
|
+
|
|
78
|
+
**立即执行:** 使用 Skill 工具加载 subagent-driven-development 技能。禁止跳过此步骤。
|
|
79
|
+
|
|
80
|
+
技能加载后,主会话协调、实现代理实施;委派前读取 subagent-dispatch.md,按工作包逐 ID 验收。外部 Skill 不新建工作区、不改变配置、不执行最终收尾。派发失败时保存原因,不擅自更换策略。
|
|
81
|
+
|
|
82
|
+
非 autonomous 的 tdd 策略首次实施时,由实施者加载:
|
|
83
|
+
|
|
84
|
+
**立即执行:** 使用 Skill 工具加载 test-driven-development 技能。禁止跳过此步骤。
|
|
85
|
+
|
|
86
|
+
技能加载后,按当前已确认任务执行。tdd 先确认测试因待实现行为而失败,再实施并记录转绿结果。已有有效证据无需重演,不回退代码伪造 RED。按风险运行相关检查;Build 做任务级或分段审查,Verify 做唯一最终集成审查。必须解决 CRITICAL/IMPORTANT 问题;无法完成所需独立审查时报告阻塞,不用实现者自评代替。任务实际完成后勾选同一 tasks.md,由 Run 提交实现结果和检查证据。
|
|
87
|
+
|
|
88
|
+
需求变化时判断实际范围、公开行为、验收和风险;原范围内遗漏直接修复,实质扩大范围或需要重新设计时,按[需求变化后的重新确认](decision-point.md#需求变化后的重新确认)请用户决定。任务数和文件数不单独触发 full 流程重启。异常先复现、定位根因,再修复并验证;需要外部方法时按 debug-gate.md 加载相应 Skill,仍沿用当前 Run。
|
|
89
|
+
|
|
90
|
+
## Verify
|
|
91
|
+
|
|
92
|
+
核对任务完成、实际改动范围、构建与相关测试、安全问题、目标及全部验收场景,并检查实现与当前规格和技术设计一致。风险决定深度,不以文件数直接决定全量测试;tweak 的 delta spec 是正常产物,存在时必须验证规格一致性。
|
|
93
|
+
|
|
94
|
+
review_mode 为 standard 或 thorough 时,由独立 reviewer 对最终 diff 完成唯一最终集成审查;覆盖当前输入的有效审查可以复用,输入变化只补受影响部分。off 时记录跳过原因;full autonomous 仍要求独立审查。autonomous 不依赖外部验证或审查 Skill,其他策略进入实际验证时:
|
|
95
|
+
|
|
96
|
+
**立即执行:** 使用 Skill 工具加载 verification-before-completion 技能。禁止跳过此步骤。
|
|
97
|
+
|
|
98
|
+
技能加载后,只采用验证方法,使用当前候选和有效证据。非 autonomous 且 review_mode 为 standard 或 thorough 的最终集成审查:
|
|
99
|
+
|
|
100
|
+
**立即执行:** 使用 Skill 工具加载 requesting-code-review 技能。禁止跳过此步骤。
|
|
101
|
+
|
|
102
|
+
技能加载后,审查当前最终 diff,复用仍有效的独立结论,不追加第二次最终审查。完整规格验证时:
|
|
103
|
+
|
|
104
|
+
**立即执行:** 使用 Skill 工具加载 openspec-verify-change 技能。禁止跳过此步骤。
|
|
105
|
+
|
|
106
|
+
<!-- external-openspec-skill-override -->
|
|
107
|
+
|
|
108
|
+
技能加载后,OpenSpec 命令通过 `comet classic openspec -- <args...>`,路径使用已绑定的 `<classic-*>` 根目录。核对 tasks、proposal、能力场景、高层与技术设计,以及 delta spec 与设计的一致性。
|
|
109
|
+
|
|
110
|
+
将实际结果、证据、独立审查结论、未执行项和已接受偏差写入报告。明确可修复的失败在前三次内按主 Skill 回 Build;CRITICAL/IMPORTANT 不可豁免。WARNING/SUGGESTION 涉及行为、范围或风险取舍时由用户决定;安全局部修复直接处理。已有 verify_failures >= 3 时,先让用户选择继续修复或停止流程寻求外部决定。失败、超时、阻塞和未执行均不算通过。
|
|
111
|
+
|
|
112
|
+
## 检查复用
|
|
113
|
+
|
|
114
|
+
按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 TDD 的 RED 与局部调试照常执行。结果复用不改变用户选择的审查要求,也不代替全部验收项。
|
|
115
|
+
|
|
116
|
+
## 预设范围复核
|
|
117
|
+
|
|
118
|
+
hotfix/tweak 的 Build、Verify 和 Archive 都核对已批准需求。完成任务的 checkbox 和 `state tasks --assign-ids` 添加的任务标识不改变需求;proposal、设计、规格或任务正文发生变化时,恢复已批准内容,或在 Build 使用主 Skill 的 `propose-escalation` 提交当前范围,再按[需求变化后的重新确认](decision-point.md#需求变化后的重新确认)取得同一预设继续或升级 full 的新决定。继续批准绑定提案时的实际内容;提案后再次改动时先恢复提案内容,或选择升级 full 并重新确认设计,不沿用旧批准。
|
|
119
|
+
|
|
120
|
+
hotfix 先复现根因,保留真实失败证据;可自动化时先运行失败回归,再修复并确认转绿,最后检查根因已消除。hotfix 使用 direct/direct/off 默认配置,任务数不决定是否升级。
|
|
121
|
+
|
|
122
|
+
tweak 使用 direct,并采用 OpenSpec apply 方法:
|
|
123
|
+
|
|
124
|
+
**立即执行:** 使用 Skill 工具加载 openspec-apply-change 技能。禁止跳过此步骤。
|
|
125
|
+
|
|
126
|
+
<!-- external-openspec-skill-override -->
|
|
127
|
+
|
|
128
|
+
技能加载后,通过 `comet classic openspec -- status --change <name> --json` 和 `comet classic openspec -- instructions apply --change <name> --json` 获取或复用有效结果,读取列出的 contextFiles 与全部 apply 指令,逐项实现并勾选同一 tasks.md,保留格式检查、相关测试与回归结果。路径使用 `<classic-*>` 根目录。full 不使用此预设 apply 路径。
|
|
129
|
+
|
|
130
|
+
新增功能、公共 API、schema、跨模块协调或深层架构变化时,请用户决定继续预设或升级 full。hotfix 超过 4 个、tweak 超过 6 个交付文件只触发范围复核,不自动升级。仅文件数超限且范围、验收与风险不变时,可复用当前 change 的 rulings.md:`status: active`、匹配 workflow、`decision: continue-on-file-count-only`、已确认 scope、`allowed-file-categories: implementation, tests, user-docs, config, generated`、`authorization-basis: user-explicit` 和 reason。首次无有效授权时先询问;已有授权时报告总数、分类、范围对应关系及记录位置后继续。范围、风险、验收、workflow 或文件类别改变时标为 invalidated,再请用户决定。SDK 使用主 Skill 的 escalation Wait,升级保留同一 Run 与工作区,进入 full Design,不执行 Compat 的状态清空命令。
|
|
131
|
+
|
|
132
|
+
## Archive 与 Git 交付
|
|
133
|
+
|
|
134
|
+
使用当前验证证据、绑定分支、remote 和 PR base,展示归档影响与本 change 的改动归属。已有授权覆盖相同目标时沿用,只补未完成的交付;目标变化或授权缺失时再问。local 只归档并提交,push 再推送,pr 推送后创建 PR;reverify 回 Verify,later 保留当前工作。target branch 与 PR base 分别核对,不能混用。
|
|
135
|
+
|
|
136
|
+
Guard apply 自带预检与副作用边界复查,常规提交直接执行主 Skill 的 apply 命令;诊断时才预览。归档后核对 Runtime 返回的实际路径,显式暂存本 change 的实现、归档文件、主 spec 和设计/计划标注,审查 staged diff 后创建唯一归档提交。保留无关改动;提交后不再修改已封存的归档目录。已有提交则复用,push/PR 结果未知先只读核对远端,不重复执行。完成实际 Git 交付后用真实 SHA 和 PR URL 提交 complete-delivery,由 Runtime 核对通过并结束 Run 才宣告完成。
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Comet 子代理开发规则
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/subagent-dispatch.md`
|
|
4
|
+
|
|
5
|
+
在 `build_mode: subagent-driven-development` 下,或 autonomous 需要委派任务、安排审查时,读取本文件。前者先加载同名 Superpowers Skill,再执行这里的规则;autonomous 直接执行,不要求加载外部执行 Skill。执行方式、任务验收、复查次数上限和五阶段收尾仍由 Classic 规定。外部 Skill 完成任务后返回 comet-build,不再自行追加 final review,也不调用 finishing-a-development-branch。
|
|
6
|
+
|
|
7
|
+
## Runtime 与任务权威
|
|
8
|
+
|
|
9
|
+
SDK 与 Compat 共用本节的任务读取、稳定 ID、勾选和协调记录命令。它们只操作 `tasks.md`、计划中的任务显示及协调记录,不推进 Run、不提交检查、不批准阶段。SDK 的阶段、Action 和决定始终以当前 Run 为准;进度记录成功不等于 Build 完成,仍须使用当前 continuation 的完成命令。恢复时先读取 Run,再核对任务、平台会话与协调记录。
|
|
10
|
+
|
|
11
|
+
## 开始前核对任务
|
|
12
|
+
|
|
13
|
+
1. 读取一次计划、确认的设计和 `comet state check <name> build --json` 返回的配置。范围、文件或配置变化后刷新相应材料。
|
|
14
|
+
2. 开始前检查计划:它不能与规格、验收要求或全局约束冲突。能通过查看仓库解决的疑问自行调查;涉及目标或授权变化的问题,集中向用户询问。
|
|
15
|
+
3. 优先使用本轮入口返回的任务摘要;需要逐项需求和 ID 时,才运行 `comet state tasks <name> --json`。任务完成状态只以 `tasks.md` 为准。根据依赖关系选择 task ID,不用行号、顺序或可能变化的标题匹配任务。
|
|
16
|
+
4. `needsIds: true` 时运行 `comet state tasks <name> --assign-ids --json`,更新受影响的交接文件和计划中的任务对应关系。保留已有 ID。旧计划中仍有复选框时,按 context-recovery.md 核对实际实现、检查结果和审查记录,明确 ID 对应关系后再同步。不能因为未勾选就重复实施,也不能擅自丢弃旧计划中额外存在的实际任务。
|
|
17
|
+
|
|
18
|
+
主会话负责分配任务、整合改动和验收,不能与仍在工作的实现子代理(implementer)同时修改同一范围。subagent-driven-development 模式下,主会话不能代替子代理编写实现;autonomous 可以先明确收回已分配的任务、核对已有成果并保存检查点,再自行实施。确认改动已出现在当前工作区并验收通过后继续,不逐个任务询问。用户要求暂停、授权存在歧义,或出现下述阻塞情况时,停止受影响的工作。
|
|
19
|
+
|
|
20
|
+
## 如何分组和分配任务
|
|
21
|
+
|
|
22
|
+
默认按可以独立验收的结果分配任务。同一模块中,使用相同局部上下文且依赖关系明确的关联任务,可以组成范围明确的一组任务,由同一个实现子代理连续完成。分配时明确 taskIds、允许修改的范围、执行顺序、验收要求和反馈时机。不要机械地限定为 2–3 个小任务,也不要向同一会话无限追加任务。
|
|
23
|
+
|
|
24
|
+
任务分组不会改变任务 ID。仍须逐 ID 报告、验收和勾选,不能因一项通过就把整组标为完成。thorough 允许同一个实现子代理继续工作,但每个任务仍须独立审查。出现范围变化、依赖冲突或新风险时,暂停受影响的任务,先核对已完成部分,再调整后续任务安排;不能擅自追加任务。
|
|
25
|
+
|
|
26
|
+
同一组任务可以交给同一个实现子代理,修复优先返回原会话。出现以下任一情况时,先保存检查点,再停止复用该会话:任务跨模块或范围明显变化;上下文过多,无法可靠保留约束;会话无法恢复;连续两次反馈仍是同一阻塞,且没有新增实现或证据。恢复前先调查原因,只交接尚未完成的任务和反馈;不能无限新建会话反复审查。审查子代理(reviewer)始终独立于实现子代理,不能让负责实现的同一角色审查自己的代码。子代理不再向下派发任务,由主会话统一协调。
|
|
27
|
+
|
|
28
|
+
## 交接与证据
|
|
29
|
+
|
|
30
|
+
给子代理的说明只包含当前任务需要的内容:task ID 与完整需求、计划和设计的引用、允许修改的范围、依赖的接口、配置中的产物语言、必须执行的检查,以及反馈格式。较长的需求、报告和审查反馈,通过外部 Skill 支持的文件方式交接;主会话只保留路径和必要摘要,不反复粘贴累计对话。模型沿用用户与平台配置,根据可用能力分配角色,不要求固定的模型名称。
|
|
31
|
+
|
|
32
|
+
实现子代理返回 `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`,并逐 task ID 列出修改的文件、提交引用、检查命令与实际结果、未完成内容和发现的风险。它只负责实现和自测,不勾选任务。主会话确认文件和提交已出现在当前工作区后,才能验收;在隔离副本中完成的改动,必须先整合回来。
|
|
33
|
+
|
|
34
|
+
若 `tdd_mode: tdd`,负责实现和修复的子代理必须提供实际执行的 RED 失败命令、GREEN 通过命令和结果摘要,并确认 RED 的失败原因正是待实现的行为。autonomous 无需加载外部 TDD Skill;其他策略在新的独立上下文中加载 test-driven-development,已有完整上下文时不重复加载。证据缺失时,只补充现在可以执行的验证,并如实说明历史证据缺口;不能回退代码伪造 RED。direct 不要求逐项提供 RED/GREEN,但仍须执行相关检查并保留缺陷回归证据。
|
|
35
|
+
|
|
36
|
+
## 风险与复查次数
|
|
37
|
+
|
|
38
|
+
以下情况需要进一步检查风险:跨模块协调;认证、授权、加密、SQL、外部输入或凭证;并发、锁、共享可变状态;数据/schema 迁移;公共 API 变化;子代理返回 DONE_WITH_CONCERNS。主会话必须同时核对实际 diff 和子代理报告。改动超过 200 行时进一步检查复杂度,不能只凭行数判断风险。机械性改动或生成文件本身不导致升级,但其对应源码、安装行为和运行时接口要求仍须审查。
|
|
39
|
+
|
|
40
|
+
| `review_mode` | Build 任务审查 | 修复后复查上限 |
|
|
41
|
+
| ------------- | ---------------------------------------------------------------------- | -------------- |
|
|
42
|
+
| `off` | 不自动分配审查子代理 | 0 |
|
|
43
|
+
| `standard` | 仅审查有风险的任务,由同一个审查子代理检查是否符合规格以及代码质量 | 1 轮 |
|
|
44
|
+
| `thorough` | 每个任务都由独立的审查子代理检查是否符合规格以及代码质量,并逐 ID 验收 | 2 轮 |
|
|
45
|
+
|
|
46
|
+
这里的安排取代外部 Skill 默认的审查步骤,不另外叠加一套审查。初审必须读取实际需求、diff 和证据,不能只看实现摘要。复查只覆盖未解决问题、修复及新增风险,不重新分析全部需求,也不重新计算已用复查次数。已经有可信检查结果时,先核对它是否仍适用;只有证据不足、输入发生变化或出现新风险时,才补充检查。
|
|
47
|
+
|
|
48
|
+
审查子代理应保持独立判断,不能预先要求它忽略某类问题。CRITICAL/IMPORTANT 问题必须解决;达到复查次数上限后仍未解决的,记录为 `BLOCKED`,请用户决定下一步。`off` 不允许忽略测试失败、异常调试协议或用户明确要求。只有实际核对并证明现有实现已经满足要求,才能记录理由后关闭该问题,不能凭乐观推断判定通过。
|
|
49
|
+
|
|
50
|
+
## 验收任务并保存进度
|
|
51
|
+
|
|
52
|
+
主会话按 context-recovery.md 的 schemaVersion:1 JSON 示例,使用 `comet state checkpoint <name> --file <json-path>` 保存协调状态。Runtime 检查数据后生成 Markdown,不手工维护 subagent-progress.md。读取结果为 `{checkpoint, stale}`;stale 时先核对实际成果。分配任务前、取得会话 ID 后,以及审查、验收或遇到阻塞时,都要保存记录。普通反馈可以合并保存,已验收的任务不重复分配。检查点不能作为另一套任务完成清单。
|
|
53
|
+
|
|
54
|
+
不超出规格、可以撤回的实现决定可自主处理。把影响后续工作的决定、依据和关联 task ID 保存到 `<classic-change-dir>/.comet/rulings.md`,在外部 Skill 的临时文件被清理前,保存必要结论和证据引用。扩大范围、修改规格或验收要求、接受重要缺陷、安全例外,以及会改变外部系统的操作,仍需用户授权。不能仅依靠临时会话或外部 Skill 的内部目录恢复工作。
|
|
55
|
+
|
|
56
|
+
逐项按配置验收后,使用本次读取的 revision 记录完成:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
comet state task-complete <name> <task-id> --json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
此命令只记录完成状态,不能替代验收。因需求变更而被拒绝时,重新读取任务和受影响的设计,核对实现是否仍符合要求,不能只换成新 revision 就盲目重试。仅更新完成状态不会改变 revision;命令支持幂等重试。按已有提交策略保存进度,不要求每个小任务都单独创建一次进度提交。
|
|
63
|
+
|
|
64
|
+
所有任务验收完成后,立即返回 `comet-build` 执行退出检查。Build 不追加覆盖整个分支的审查;由 `comet-verify` 按 `review_mode` 完成唯一一次最终集成审查,再由 Archive 收尾。
|
|
65
|
+
|
|
66
|
+
## 中断恢复
|
|
67
|
+
|
|
68
|
+
按 context-recovery.md 获取入口返回的最新状态信息;coordination 摘要不足时,才用 `comet state checkpoint <name>` 读取详情,必要时按引用读取 rulings。核对 revision、实际提交、文件和证据后,从原阶段继续,保留有效审查结果和已用复查次数。
|
|
69
|
+
|
|
70
|
+
- 未勾选但已有实现的任务,先核对验收,不重复实现;已提交但未验收的任务保持未完成。
|
|
71
|
+
- 一组任务中只恢复尚未验收的任务;已完成任务以 tasks.md 为准,旧计划中的对应复选框只同步显示状态。
|
|
72
|
+
- 任务被删、改名或需求变化时先重新映射和判断影响;缺少映射不能猜成第一个未勾选任务。
|
|
73
|
+
- 检查点缺失时先调查当前工作树和历史;仅对确认未实现的任务新建派发,不能把“无检查点”当作“无实现”。
|
|
74
|
+
- 任务分配失败或会话不可用时,记录实际原因,停止对应任务的执行与审查,并按恢复流程处理;不能擅自改变用户选定的执行方式。
|
|
75
|
+
- 全部任务完成时返回 `comet-build`,不恢复旧的 Build final-review/final-fix 状态。
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Classic 工作区选择参考
|
|
2
|
+
|
|
3
|
+
只在创建 change 时读取。已有 change 使用已保存的工作区绑定,并进入返回的 `projectRoot`。
|
|
4
|
+
|
|
5
|
+
用户明确表达并行、同时处理或多个会话时,直接使用 `worktree`,不再询问三种方式。未指定隔离方式且没有明确并行意图时,出现以下任一情况才询问用户:
|
|
6
|
+
|
|
7
|
+
- 当前目录有未提交改动;
|
|
8
|
+
- 已有其他尚未归档的 Classic change;
|
|
9
|
+
- 用户要求并行开发或隔离工作,但没有指定方式。
|
|
10
|
+
|
|
11
|
+
没有这些情况时使用 Runtime 默认的 `current`。
|
|
12
|
+
|
|
13
|
+
需要询问时,请用户单选工作区隔离方式:
|
|
14
|
+
|
|
15
|
+
| 选项 | 方式 | 实际影响 |
|
|
16
|
+
| ---- | ------------------------- | ---------------------------------------------------------------------- |
|
|
17
|
+
| A | 当前目录(`current`) | 沿用当前分支和目录,不创建新的 Git 分支或工作目录 |
|
|
18
|
+
| B | 新分支(`branch`) | 在当前目录切换到新的 change 分支;要求当前工作区干净 |
|
|
19
|
+
| C | 新 worktree(`worktree`) | 创建或复用独立分支和工作目录,适合并行 change 或当前目录已有未提交工作 |
|
|
20
|
+
|
|
21
|
+
展示符合当前状态和用户要求的全部合法选项,不能因为猜测后续命令可能失败就额外排除选项。用户明确要沿用当前分支时推荐 A;需要独立分支、但无需并行工作时推荐 B;需要并行开发、当前目录已有改动,或已有尚未归档的 Classic change 时推荐 C。
|
|
22
|
+
|
|
23
|
+
推荐只作说明,等待用户选择后再创建。已有 change 的分支如果已经登记在 Worktree 中,Runtime 会复用它;如果分支仍存在,但登记的 Worktree 已被移除,Runtime 会重建它。只有分支已重命名、被用户接管或无法确认归属时,才按恢复协议请求 rebind。提问方式遵循[澄清参考](decision-point.md):优先使用结构化单选工具;工具不可用时,使用带编号的文本选项,并暂停等待答复。只有一个合法选项时,说明原因后直接采用。
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comet-design
|
|
3
|
+
description: '完成 Classic 技术设计并请用户确认。在用户调用 /comet-design,或 Classic Runtime 进入 Design 时使用。'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Comet 阶段 2:深度设计(Design)
|
|
7
|
+
|
|
8
|
+
首次进入阶段、交接给新 Agent 或上下文恢复后,读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言),优先采用当前 continuation 或已领取 Action 的 `contextRequest`;同一阶段连续执行不重复获取。
|
|
9
|
+
|
|
10
|
+
收到入口返回的 layout 后,首次接收阶段或绑定变化时执行[阶段共用入口](../comet-classic/reference/scripts.md#阶段共用入口),复用仍有效的 [layout](../comet-classic/reference/classic-layout.md),无需先额外运行 root show;遇编辑判断时按共用入口加载编辑后续行协议。
|
|
11
|
+
|
|
12
|
+
## SDK Run 路径
|
|
13
|
+
|
|
14
|
+
首次进入当前 SDK 阶段、换 Agent 或恢复上下文时,读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节;本会话已有且仍有效时直接复用。下文按当前阶段执行;`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。
|
|
15
|
+
|
|
16
|
+
优先复用同一 change、工作区和 Run 的最新有效响应中的 `agent.continuation`、`data.nextAction`、phase、revision 和路径摘要。只有冷恢复、工作区或外部状态变化、响应版本已过期或缺少当前步骤必要信息时,才运行 `comet state next <change-name> --json`;不要因加载下一 Skill 再读一次。后续写操作仍由 Runtime 校验当前版本与证据,不能用缓存跳过检查或批准。当 `data.runtimeFormat` 为 `sdk` 时,只执行本节的状态命令;设计探索、提问与正式文档要求见 SDK 方法参考的 Design 章节,状态操作使用本节命令。`data.phase` 必须为 `design`;已进入 Build 时交回当前阶段入口。`data.nextAction.kind` 为 `reconcile` 时,运行 `comet state check <change-name> design --recover --json` 核对已领取 Action 的原结果,在结果明确前停止,不重新提案或重发工作。
|
|
17
|
+
|
|
18
|
+
1. 待执行 Action 为 `full.design.handoff` 时,复用当前响应的 layout 与产物引用;缺少时才运行 `comet state check <change-name> design --json`,直接读取当前 OpenSpec proposal、tasks、delta specs 和已有 design.md 中本次设计需要的内容。按 SDK 方法参考的 Design 章节形成候选技术方案;此时还没有 SDK handoff 包,不执行旧 `comet handoff ... --write`,也不把手写摘要当作 SDK handoff。持续保存 `brainstorm-summary.md`,未确认内容标为候选。
|
|
19
|
+
2. 如候选方案需要 Spec Patch,先按 SDK 方法参考的设计确认规则向用户说明具体补丁并取得明确同意,再修改 delta spec。范围发生实质变化时重新澄清。待 OpenSpec 来源稳定后,执行 `comet state propose-design <change-name> --proposal "<candidate-summary>"`,其中摘要必须覆盖将请用户确认的方案、关键取舍、风险和 Spec Patch;保存返回的 `data.wait.proposalHash` 为 `<proposalHash>`。此命令生成并记录可追溯的 handoff;优先使用提案结果中的 `data.configuration.handoffContext`,缺少时再运行 `comet state next <change-name> --json`;读取 `data.configuration.handoffContext` 对应的 Markdown 包,核对它与候选方案及当前源文件一致。用户尚未决定时,恢复应复用这个 Wait,不重复运行 propose-design。
|
|
20
|
+
3. 按 `comet-classic/reference/decision-point.md` 核对当前方案与已有授权。授权覆盖时记录依据并继续;需要新决定时,先按[变化说明](../comet-classic/reference/decision-point.md#需求变化后的重新确认)说明影响,展示当前方案并等待答复。使用当前提案哈希执行 `comet state decide-design <change-name> --proposal-hash <proposalHash> --choice <approved|rejected>`:已有有效批准或委托授权覆盖当前方案时填 `approved`,用户要求调整时填 `rejected` 并重新提案;暂缓时保留 Wait。来源变化使旧哈希失效时核对差异,使用当前提案记录决定,不复用过期哈希。
|
|
21
|
+
4. 已批准后,按 SDK 方法参考写入唯一 Design Doc,包含要求的 frontmatter;如恢复时 `nextAction.kind` 已为 `action` 且 stepId 为 `full.design.document`,直接从这一步继续。直接运行 `comet state complete-design <change-name> --design-doc <design-doc-ref> --approval-hash <proposalHash>`,由同一 Run 提交文档 Action 和证据。提交失败时保留原 Run 并按具体原因处理;实际状态文件由 Runtime 同步,Agent 不手动推进 phase。成功后按同次响应的 Build Action 与 continuation 路由;缺少续行信息时才运行 `comet state next <change-name> --json`。
|
|
22
|
+
|
|
23
|
+
## Compat 路径
|
|
24
|
+
|
|
25
|
+
以下旧 Runtime 步骤仅用于 `runtimeFormat: compat`。必须读取 [Compat 操作](reference/compat.md),按其中当前阶段继续;SDK 不加载该参考。
|