comet-build

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comet 阶段 3：计划与构建（Build）

Comet Phase 3: Planning and Building

前置条件

Preconditions

Design Doc 已创建（阶段 2 完成）
活跃 change 存在

Design Doc has been created (Phase 2 completed)
An active change exists

步骤

Steps

0. 入口状态验证（Entry Check）

0. Entry Check

执行入口验证：

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> build

验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。

Perform entry verification:

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> build

Proceed to Step 1 after verification passes. If verification fails, the script will output specific failure reasons.

1. 制定计划

1. Develop a Plan

立即执行： 使用 Skill 工具加载

superpowers:writing-plans

技能。禁止跳过此步骤。

技能加载后，按其指引制定计划。计划要求：

保存至

docs/superpowers/plans/YYYY-MM-DD-<feature>.md

引用设计文档，拆分为可执行任务
Plan 文件头必须包含关联元数据：

yaml

---
change: <openspec-change-name>
design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
base-ref: <git rev-parse HEAD before implementation>
---

base-ref

用于验证阶段跨提交统计改动规模。创建计划时先记录当前提交：

bash

git rev-parse HEAD

Execute immediately: Use the Skill tool to load the

superpowers:writing-plans

skill. Skipping this step is prohibited.

After loading the skill, follow its guidance to develop a plan. The plan requirements are:

Save to

docs/superpowers/plans/YYYY-MM-DD-<feature>.md

Reference the design document and split it into executable tasks
The plan file header must include associated metadata:

yaml

---
change: <openspec-change-name>
design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
base-ref: <git rev-parse HEAD before implementation>
---

base-ref

is used to verify the scale of changes across commits during the phase. Record the current commit when creating the plan:

bash

git rev-parse HEAD

2. 更新计划状态

2. Update Plan Status

先记录 plan 路径：

bash

bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md

无需手动更新 phase，guard 会在退出条件满足后自动流转。

First, record the plan path:

bash

bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md

There is no need to manually update the phase; the guard will automatically transition after the exit conditions are met.

3. 工作区隔离

3. Workspace Isolation

计划已写入当前分支。在开始执行前，选择工作区隔离方式：

选项	方式	说明
A	创建分支	在当前仓库创建新分支，简单快速
B	创建 Worktree	隔离工作区，完全独立，适合并行开发

推荐规则：

变更涉及 ≤ 3 个文件 → 推荐 A
需要并行开发、当前分支有未提交工作 → 推荐 B

用户选择后，更新

isolation

字段。

isolation

只允许以下值之一：

bash

bash "$COMET_STATE" set <name> isolation <value>

```
branch
```
```
worktree
```

<IMPORTANT> 这是脚本级硬约束，不是建议。full workflow 初始化时 `isolation` 可以暂时为 `null`，但只允许存在到本步骤之前。进入实现前必须停下来询问用户并写入 `branch` 或 `worktree`。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。 </IMPORTANT>

执行隔离：

branch：执行
```
git checkout -b <change-name>
```
，后续工作在新分支上进行
worktree：调用
```
superpowers:using-git-worktrees
```
技能或使用原生
```
EnterWorktree
```
工具创建隔离工作区

创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。

The plan has been written to the current branch. Before starting execution, select a workspace isolation method:

Option	Method	Description
A	Create a branch	Create a new branch in the current repository, simple and fast
B	Create a Worktree	Isolate the workspace, fully independent, suitable for parallel development

Recommendation Rules:

Changes involve ≤ 3 files → Recommend A
Parallel development is needed, or there are uncommitted changes in the current branch → Recommend B

After the user selects, update the

isolation

field.

isolation

only allows one of the following values:

bash

bash "$COMET_STATE" set <name> isolation <value>

```
branch
```
```
worktree
```

<IMPORTANT> This is a script-level hard constraint, not a suggestion. `isolation` can be temporarily `null` when initializing the full workflow, but only until before this step. You must stop to ask the user and write `branch` or `worktree` before entering implementation. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail. </IMPORTANT>

Execute Isolation:

branch: Execute
```
git checkout -b <change-name>
```
, and subsequent work will be done on the new branch
worktree: Call the
```
superpowers:using-git-worktrees
```
skill or use the native
```
EnterWorktree
```
tool to create an isolated workspace

After creating isolation, confirm that the plan file is accessible (branch method is naturally accessible; worktree method requires confirming the plan has been committed).

4. 选择执行方式

4. Select Execution Method

向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：

选项	技能	适用场景
A	`superpowers:subagent-driven-development`	任务独立、复杂度高、需要双阶段审查
B	`superpowers:executing-plans`	任务简单、无子agent环境、轻量快速

推荐规则：

任务数 ≥ 3 → 推荐 A
任务数 ≤ 2 且无跨模块依赖 → 推荐 B
来自 hotfix 路径 → 推荐 B

用户选择后，更新

build_mode

字段。

build_mode

只允许以下值之一：

bash

bash "$COMET_STATE" set <name> build_mode <value>

```
subagent-driven-development
```
```
executing-plans
```
```
direct
```
（默认仅 hotfix/tweak preset 使用）

full workflow 不得默认使用

direct

。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：

bash

bash "$COMET_STATE" set <name> direct_override true
bash "$COMET_STATE" set <name> build_mode direct

没有

direct_override: true

时，full workflow 的

build_mode=direct

会被 guard 和状态转换同时拦截。

然后，立即执行： 使用 Skill 工具加载对应技能。禁止跳过此步骤。

如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。

技能加载后，按其指引执行：

按计划执行任务
完成 tasks.md 勾选（
```
- [ ]
```
→
```
- [x]
```
）
每个任务完成后提交代码

Show the user a summary of the plan (number of tasks, involved modules), then ask for the execution method:

Option	Skill	Applicable Scenario
A	`superpowers:subagent-driven-development`	Independent tasks, high complexity, requiring two-stage review
B	`superpowers:executing-plans`	Simple tasks, no subagent environment, lightweight and fast

Recommendation Rules:

Number of tasks ≥ 3 → Recommend A
Number of tasks ≤ 2 and no cross-module dependencies → Recommend B
From hotfix path → Recommend B

After the user selects, update the

build_mode

field.

build_mode

only allows one of the following values:

bash

bash "$COMET_STATE" set <name> build_mode <value>

```
subagent-driven-development
```
```
executing-plans
```
```
direct
```
(only used by hotfix/tweak preset by default)

The full workflow must not use

direct

by default. Only when the user explicitly requests to skip the plan execution skill and you have recorded an explicit override is it allowed:

bash

bash "$COMET_STATE" set <name> direct_override true
bash "$COMET_STATE" set <name> build_mode direct

Without

direct_override: true

build_mode=direct

in the full workflow will be intercepted by both the guard and state transition.

Then, execute immediately: Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.

If the selected Superpowers skill is unavailable, stop the process and prompt to install or enable the corresponding skill; do not replace this step with ordinary dialogue.

After loading the skill, follow its guidance to execute:

Execute tasks according to the plan
Tick off tasks.md (
```
- [ ]
```
→
```
- [x]
```
)
Commit code after each task is completed

5. Spec 增量更新

5. Spec Incremental Update

实施过程中发现初版 spec 不完整时，按变更规模分级处理：

规模	触发条件	做法
小	遗漏验收场景、边界条件	直接编辑 delta spec + design.md，追加 tasks.md 任务
中	接口变更、新增组件、数据流变化	重新 `superpowers:brainstorming` 更新 Design Doc + delta spec
大	全新 capability 需求	`/opsx:new` 创建独立 change

50% 阈值判定：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，应考虑拆分为新 change。

原则：

delta spec 是活文档，本阶段期间随时可修改
每次更新应提交，commit message 说明变更原因
不提前同步到 main spec，归档时统一同步
小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移

When it is found that the initial spec is incomplete during implementation, handle it in stages according to the scale of changes:

Scale	Trigger Condition	Action
Small	Missing acceptance scenarios, boundary conditions	Directly edit delta spec + design.md, append tasks to tasks.md
Medium	Interface changes, new components added, data flow changes	Re-run `superpowers:brainstorming` to update Design Doc + delta spec
Large	New capability requirements	Create an independent change with `/opsx:new`

50% Threshold Judgment: Based on the initial total number of tasks in tasks.md, if the number of newly added tasks exceeds half of this total, it is considered to be beyond the original plan scope, and should be considered for splitting into a new change.

Principles:

Delta spec is a living document and can be modified at any time during this phase
Submit each update, with the commit message explaining the reason for the change
Do not synchronize to the main spec in advance; synchronize uniformly during archiving
When making small-scale increments by directly modifying the delta spec, note it in the commit message to facilitate judging design doc drift during archiving

6. 上下文管理

6. Context Management

Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：

每完成一个 task：立即勾选 tasks.md 并提交代码，确保
```
.comet.yaml
```
和文件状态持久化
上下文压缩后恢复：读取
```
.comet.yaml
```
的
```
phase
```
字段确认仍在 build 阶段，读取 plan 文件头的
```
base-ref
```
，再读取 tasks.md 找到下一个未勾选任务继续执行
用户手动修改恢复：按
```
comet/reference/dirty-worktree.md
```
协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 5「Spec 增量更新」分级处理
长任务拆分：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交

Build is the longest phase and may span a large number of tasks. To support breakpoint recovery after context compression:

After completing each task: Immediately tick off tasks.md and commit code to ensure
```
.comet.yaml
```
and file status are persisted
Recovery after context compression: Read the
```
phase
```
field in
```
.comet.yaml
```
to confirm it is still in the build phase, read the
```
base-ref
```
in the plan file header, then read tasks.md to find the next unticked task and continue execution
Recovery from manual user modifications: Handle uncommitted changes according to the
```
comet/reference/dirty-worktree.md
```
protocol. This protocol defines inspection steps, attribution classification, and prohibitions. Special handling during the build phase:
1. After attribution, if the diff implies that the plan or spec has changed, handle it in stages according to Step 5 "Spec Incremental Update"
Long task splitting: When a single task involves more than 200 lines of code changes, consider splitting it into multiple subtasks and submitting them separately

退出条件

Exit Conditions

tasks.md 全部勾选
代码已提交
已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
```
isolation
```
已写为
```
branch
```
或
```
worktree
```

build_mode

已写为

subagent-driven-development

、

executing-plans

或带显式 override 的

direct

阶段守卫：运行

bash "$COMET_GUARD" <change-name> build --apply

，全部 PASS 后自动流转到

phase: verify

Guard 会优先读取项目配置中的命令：

yaml

build_command: <build command>
verify_command: <verify command>

配置位置可为 change 的

.comet.yaml

，也可为仓库根目录的

.comet.yaml

comet.yaml

.comet.yml

comet.yml

。未配置时才回退到

npm run build

、Maven 或 Cargo 的默认探测。构建失败时 guard 会打印失败命令输出，作为排查证据。

退出前运行 guard 自动流转：

bash

bash "$COMET_GUARD" <change-name> build --apply

状态文件自动更新为

phase: verify

、

verify_result: pending

。

All items in tasks.md are ticked
Code has been committed
The corresponding build/test command for the project has been explicitly run and passed (do not rely solely on the guard's automatic guess)
```
isolation
```
has been set to
```
branch
```
or
```
worktree
```

build_mode

has been set to

subagent-driven-development

executing-plans

, or

direct

with an explicit override

Phase Guard: Run
```
bash "$COMET_GUARD" <change-name> build --apply
```
, and automatically transition to
```
phase: verify
```
after all checks PASS

The guard will prioritize reading commands from the project configuration:

yaml

build_command: <build command>
verify_command: <verify command>

The configuration can be located in the change's

.comet.yaml

, or the repository root's

.comet.yaml

comet.yaml

.comet.yml

comet.yml

. If not configured, it will fall back to default detection for

npm run build

, Maven, or Cargo. If the build fails, the guard will print the failed command output as troubleshooting evidence.

Run the guard for automatic transition before exiting:

bash

bash "$COMET_GUARD" <change-name> build --apply

The status file will be automatically updated to

phase: verify

verify_result: pending

自动流转

Automatic Transition

退出条件满足后，无需等待用户再次输入，直接执行下一阶段：

REQUIRED NEXT SKILL: 调用
comet-verify
skill 进入验证与收尾阶段。

After the exit conditions are met, do not wait for the user to input again, directly execute the next phase:

REQUIRED NEXT SKILL: Invoke the
comet-verify
skill to enter the verification and finalization phase.