Comet Phase 3: Planning and Building

Preconditions

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

Steps

0. Entry Check

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. Develop a Plan

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. Update Plan Status

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. Workspace Isolation

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. Select Execution Method

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 Incremental Update

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. Context Management

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

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

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.

comet-build

NPX Install

Tags

SKILL.md Content (Chinese)

Comet Phase 3: Planning and Building

Preconditions

Steps

0. Entry Check

1. Develop a Plan

2. Update Plan Status

3. Workspace Isolation

4. Select Execution Method

5. Spec Incremental Update

6. Context Management

Exit Conditions

Automatic Transition