# Comet 子代理开发规则

规范路径：`comet-classic/reference/subagent-dispatch.md`

在 `build_mode: subagent-driven-development` 下，或 autonomous 需要委派任务、安排审查时，读取本文件。前者先加载同名 Superpowers Skill，再执行这里的规则；autonomous 直接执行，不要求加载外部执行 Skill。执行方式、任务验收、复查次数上限和五阶段收尾仍由 Classic 规定。外部 Skill 完成任务后返回 comet-build，不再自行追加 final review，也不调用 finishing-a-development-branch。

## 开始前核对任务

1. 读取一次计划、确认的设计和 `comet state check <name> build --json` 返回的配置。范围、文件或配置变化后刷新相应材料。
2. 开始前检查计划：它不能与规格、验收要求或全局约束冲突。能通过查看仓库解决的疑问自行调查；涉及目标或授权变化的问题，集中向用户询问。
3. 优先使用本轮入口返回的任务摘要；需要逐项需求和 ID 时，才运行 `comet state tasks <name> --json`。任务完成状态只以 `tasks.md` 为准。根据依赖关系选择 task ID，不用行号、顺序或可能变化的标题匹配任务。
4. `needsIds: true` 时运行 `comet state tasks <name> --assign-ids --json`，更新受影响的交接文件和计划中的任务对应关系。保留已有 ID。旧计划中仍有复选框时，按 context-recovery.md 核对实际实现、检查结果和审查记录，明确 ID 对应关系后再同步。不能因为未勾选就重复实施，也不能擅自丢弃旧计划中额外存在的实际任务。

主会话负责分配任务、整合改动和验收，不能与仍在工作的实现子代理（implementer）同时修改同一范围。subagent-driven-development 模式下，主会话不能代替子代理编写实现；autonomous 可以先明确收回已分配的任务、核对已有成果并保存检查点，再自行实施。确认改动已出现在当前工作区并验收通过后继续，不逐个任务询问。用户要求暂停、授权存在歧义，或出现下述阻塞情况时，停止受影响的工作。

## 如何分组和分配任务

默认按可以独立验收的结果分配任务。同一模块中，使用相同局部上下文且依赖关系明确的关联任务，可以组成范围明确的一组任务，由同一个实现子代理连续完成。分配时明确 taskIds、允许修改的范围、执行顺序、验收要求和反馈时机。不要机械地限定为 2–3 个小任务，也不要向同一会话无限追加任务。

任务分组不会改变任务 ID。仍须逐 ID 报告、验收和勾选，不能因一项通过就把整组标为完成。thorough 允许同一个实现子代理继续工作，但每个任务仍须独立审查。出现范围变化、依赖冲突或新风险时，暂停受影响的任务，先核对已完成部分，再调整后续任务安排；不能擅自追加任务。

同一组任务可以交给同一个实现子代理，修复优先返回原会话。出现以下任一情况时，先保存检查点，再停止复用该会话：任务跨模块或范围明显变化；上下文过多，无法可靠保留约束；会话无法恢复；连续两次反馈仍是同一阻塞，且没有新增实现或证据。恢复前先调查原因，只交接尚未完成的任务和反馈；不能无限新建会话反复审查。审查子代理（reviewer）始终独立于实现子代理，不能让负责实现的同一角色审查自己的代码。子代理不再向下派发任务，由主会话统一协调。

## 交接与证据

给子代理的说明只包含当前任务需要的内容：task ID 与完整需求、计划和设计的引用、允许修改的范围、依赖的接口、配置中的产物语言、必须执行的检查，以及反馈格式。较长的需求、报告和审查反馈，通过外部 Skill 支持的文件方式交接；主会话只保留路径和必要摘要，不反复粘贴累计对话。模型沿用用户与平台配置，根据可用能力分配角色，不要求固定的模型名称。

实现子代理返回 `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`，并逐 task ID 列出修改的文件、提交引用、检查命令与实际结果、未完成内容和发现的风险。它只负责实现和自测，不勾选任务。主会话确认文件和提交已出现在当前工作区后，才能验收；在隔离副本中完成的改动，必须先整合回来。

若 `tdd_mode: tdd`，负责实现和修复的子代理必须提供实际执行的 RED 失败命令、GREEN 通过命令和结果摘要，并确认 RED 的失败原因正是待实现的行为。autonomous 无需加载外部 TDD Skill；其他策略在新的独立上下文中加载 test-driven-development，已有完整上下文时不重复加载。证据缺失时，只补充现在可以执行的验证，并如实说明历史证据缺口；不能回退代码伪造 RED。direct 不要求逐项提供 RED/GREEN，但仍须执行相关检查并保留缺陷回归证据。

## 风险与复查次数

以下情况需要进一步检查风险：跨模块协调；认证、授权、加密、SQL、外部输入或凭证；并发、锁、共享可变状态；数据/schema 迁移；公共 API 变化；子代理返回 DONE_WITH_CONCERNS。主会话必须同时核对实际 diff 和子代理报告。改动超过 200 行时进一步检查复杂度，不能只凭行数判断风险。机械性改动或生成文件本身不导致升级，但其对应源码、安装行为和运行时接口要求仍须审查。

| `review_mode` | Build 任务审查                                                         | 修复后复查上限 |
| ------------- | ---------------------------------------------------------------------- | -------------- |
| `off`         | 不自动分配审查子代理                                                   | 0              |
| `standard`    | 仅审查有风险的任务，由同一个审查子代理检查是否符合规格以及代码质量     | 1 轮           |
| `thorough`    | 每个任务都由独立的审查子代理检查是否符合规格以及代码质量，并逐 ID 验收 | 2 轮           |

这里的安排取代外部 Skill 默认的审查步骤，不另外叠加一套审查。初审必须读取实际需求、diff 和证据，不能只看实现摘要。复查只覆盖未解决问题、修复及新增风险，不重新分析全部需求，也不重新计算已用复查次数。已经有可信检查结果时，先核对它是否仍适用；只有证据不足、输入发生变化或出现新风险时，才补充检查。

审查子代理应保持独立判断，不能预先要求它忽略某类问题。CRITICAL/IMPORTANT 问题必须解决；达到复查次数上限后仍未解决的，记录为 `BLOCKED`，请用户决定下一步。`off` 不允许忽略测试失败、异常调试协议或用户明确要求。只有实际核对并证明现有实现已经满足要求，才能记录理由后关闭该问题，不能凭乐观推断判定通过。

## 验收任务并保存进度

主会话按 context-recovery.md 的 schemaVersion:1 JSON 示例，使用 `comet state checkpoint <name> --file <json-path>` 保存协调状态。Runtime 检查数据后生成 Markdown，不手工维护 subagent-progress.md。读取结果为 `{checkpoint, stale}`；stale 时先核对实际成果。分配任务前、取得会话 ID 后，以及审查、验收或遇到阻塞时，都要保存记录。普通反馈可以合并保存，已验收的任务不重复分配。检查点不能作为另一套任务完成清单。

不超出规格、可以撤回的实现决定可自主处理。把影响后续工作的决定、依据和关联 task ID 保存到 `<classic-change-dir>/.comet/rulings.md`，在外部 Skill 的临时文件被清理前，保存必要结论和证据引用。扩大范围、修改规格或验收要求、接受重要缺陷、安全例外，以及会改变外部系统的操作，仍需用户授权。不能仅依靠临时会话或外部 Skill 的内部目录恢复工作。

逐项按配置验收后，使用本次读取的 revision 记录完成：

```bash
comet state task-complete <name> <task-id> --expect <revision> --json
```

此命令只记录完成状态，不能替代验收。因需求变更而被拒绝时，重新读取任务和受影响的设计，核对实现是否仍符合要求，不能只换成新 revision 就盲目重试。仅更新完成状态不会改变 revision；命令支持幂等重试。按已有提交策略保存进度，不要求每个小任务都单独创建一次进度提交。

所有任务验收完成后，立即返回 `comet-build` 执行退出检查。Build 不追加覆盖整个分支的审查；由 `comet-verify` 按 `review_mode` 完成唯一一次最终集成审查，再由 Archive 收尾。

## 中断恢复

按 context-recovery.md 获取入口返回的最新状态信息；coordination 摘要不足时，才用 `comet state checkpoint <name>` 读取详情，必要时按引用读取 rulings。核对 revision、实际提交、文件和证据后，从原阶段继续，保留有效审查结果和已用复查次数。

- 未勾选但已有实现的任务，先核对验收，不重复实现；已提交但未验收的任务保持未完成。
- 一组任务中只恢复尚未验收的任务；已完成任务以 tasks.md 为准，旧计划中的对应复选框只同步显示状态。
- 任务被删、改名或需求变化时先重新映射和判断影响；缺少映射不能猜成第一个未勾选任务。
- 检查点缺失时先调查当前工作树和历史；仅对确认未实现的任务新建派发，不能把“无检查点”当作“无实现”。
- 任务分配失败或会话不可用时，记录实际原因，停止对应任务的执行与审查，并按恢复流程处理；不能擅自改变用户选定的执行方式。
- 全部任务完成时返回 `comet-build`，不恢复旧的 Build final-review/final-fix 状态。