|
|
# .comet.yaml 字段说明
|
|
|
|
|
|
规范路径：`comet/reference/comet-yaml-fields.md`
|
|
|
|
|
|
本文件是 `.comet.yaml` 状态文件的字段参考。按需查阅，不随 skill 一次性加载。
|
|
|
|
|
|
## 示例
|
|
|
|
|
|
```yaml
|
|
|
workflow: full
|
|
|
phase: build
|
|
|
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
|
|
|
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
|
|
|
base_ref: a1b2c3d4e5f6...
|
|
|
build_mode: subagent-driven-development
|
|
|
build_pause: null
|
|
|
subagent_dispatch: confirmed
|
|
|
tdd_mode: tdd
|
|
|
review_mode: standard
|
|
|
isolation: branch
|
|
|
verify_mode: light
|
|
|
verify_result: pending
|
|
|
verification_report: null
|
|
|
branch_status: pending
|
|
|
created_at: 2026-05-26
|
|
|
verified_at: null
|
|
|
archived: false
|
|
|
```
|
|
|
|
|
|
## 必需字段
|
|
|
|
|
|
| 字段 | 含义 |
|
|
|
|------|------|
|
|
|
| `workflow` | `full`、`hotfix` 或 `tweak` |
|
|
|
| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
|
|
|
| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
|
|
|
| `plan` | 关联的 Superpowers Plan 路径，可为空 |
|
|
|
| `base_ref` | init 时记录的 git commit SHA，用于 scale 评估。无 plan 时作为改动文件数统计基准 |
|
|
|
| `build_mode` | 已选择的执行方式，可为空 |
|
|
|
| `build_pause` | build 阶段内部暂停点。`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户选择切换模型后暂停 |
|
|
|
| `subagent_dispatch` | `null` 或 `confirmed`。仅当已确认当前平台存在真实后台 subagent / Task / multi-agent 调度能力时，`build_mode: subagent-driven-development` 才能写入并用于离开 build 阶段 |
|
|
|
| `tdd_mode` | `tdd` 或 `direct`。full workflow 离开 build 阶段前必须已选择。`tdd` 强制每个任务先写失败测试再实现；`direct` 不强制 TDD。hotfix/tweak 默认 `direct` |
|
|
|
| `review_mode` | `off`、`standard` 或 `thorough`。full workflow 离开 build 阶段前必须已选择；hotfix/tweak 默认 `off` |
|
|
|
| `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/comet-build` Step 3 前；hotfix/tweak 默认 `branch` |
|
|
|
| `verify_mode` | `light` 或 `full`，可为空 |
|
|
|
| `auto_transition` | `true` 或 `false`。只控制阶段守卫推进 phase 后是否自动调用下一个 skill；`false` 时由 `comet-state next` 输出 `manual`，暂停下一 skill 调用，但不阻止 phase 字段更新 |
|
|
|
| `verify_result` | `pending`、`pass` 或 `fail` |
|
|
|
| `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
|
|
|
| `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
|
|
|
| `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
|
|
|
| `verified_at` | 验证通过时间，可为空 |
|
|
|
| `archived` | change 是否已归档 |
|
|
|
|
|
|
## 可选字段
|
|
|
|
|
|
| 字段 | 含义 |
|
|
|
|------|------|
|
|
|
| `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`，必须显式设为 `true` |
|
|
|
| `build_command` | 项目构建命令。guard 优先运行该命令，失败时打印命令输出 |
|
|
|
| `verify_command` | 项目验证命令。verify guard 优先运行该命令，未配置时回退到构建命令 |
|
|
|
|
|
|
## 状态机硬约束
|
|
|
|
|
|
- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
|
|
|
- `build → verify` 前，`build_mode` 必须已选择
|
|
|
- `build_mode: subagent-driven-development` 必须同时有 `subagent_dispatch: confirmed`
|
|
|
- full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`
|
|
|
- full workflow 离开 build 阶段前 `review_mode` 必须已选择为 `off`、`standard` 或 `thorough`
|
|
|
- `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
|
|
|
- `build_pause` 不是执行方式，不得写入 `build_mode`
|
|
|
- 这些约束同时存在于 `comet-guard.sh build --apply` 和 `comet-state.sh transition <name> build-complete`
|
