Skip to main content
The Build phase turns the Design Doc into working code. /comet-build first creates a structured implementation plan, then pauses to let you choose how to isolate and execute the work, and finally runs through every task in sequence — checking off tasks.md and committing after each one. The result is a traceable commit history that maps directly back to your design intent.

​
Trigger

Run /comet-build directly, or let /comet auto-dispatch after Phase 2 completes. If you paused at build_pause: plan-ready, running /comet or /comet-build again resumes from where you left off without regenerating the plan.

​
What Happens

1

Implementation plan is created

The AI loads the Superpowers writing-plans skill and produces an implementation plan saved to docs/superpowers/plans/YYYY-MM-DD-<feature>.md. The plan references the Design Doc and breaks the work into executable tasks. Its frontmatter captures a base-ref (the current git commit SHA) so the verify phase can later measure the full scope of changes:
---
change: <openspec-change-name>
design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
base-ref: <git rev-parse HEAD before implementation>
---
2

Plan-ready pause — you choose isolation method and build mode

After the plan is recorded in .comet.yaml, the workflow pauses at a user decision point. You have two options:
  • Continue now — stay in the current model and immediately choose your workspace isolation method and execution mode
  • Pause to switch model — record build_pause: plan-ready and stop this invocation; resume later with /comet or /comet-build and Comet will reuse the existing plan without regenerating it
If you continue, the AI asks you to choose both your workspace isolation method and build mode in a single interaction (see tables below). These choices are recorded in .comet.yaml before any code is written.
3

Workspace is isolated

Based on your choice, the AI either creates a new git branch (git checkout -b <change-name>) or loads the Superpowers using-git-worktrees skill to set up a fully isolated worktree. The worktree path cannot be bypassed with plain shell commands — the skill must be loaded.
4

Execution skill runs the plan task by task

The AI loads the Superpowers execution skill you chose (subagent-driven-development or executing-plans) and works through each task in the plan. After each task:
  • The corresponding checkbox in tasks.md is marked [x]
  • The code is committed with a message that reflects the design intent
If build_mode is executing-plans, a code review (requesting-code-review skill) is required before the build phase can close. CRITICAL review findings must be fixed; non-CRITICAL findings may be accepted with a recorded rationale.
5

Guard validates exit conditions and advances state

Once all tasks are checked and committed, the phase guard runs project-specific build and verify commands (from .comet.yaml or the repo root config), confirms isolation and build_mode are both set, and auto-transitions .comet.yaml to phase: verify.

​
Workspace Isolation Methods

Choose the method that fits your situation. Your choice is recorded in .comet.yaml as isolation.
MethodDescriptionBest For
branchCreates a new git branch in the current repo (git checkout -b <change-name>)Changes touching ≤ 3 files, simple linear work
worktreeCreates a fully isolated git worktree via the Superpowers using-git-worktrees skillParallel development, or when the current branch has uncommitted work

​
Build Modes

Your choice of build mode determines how the AI executes the plan. It is recorded in .comet.yaml as build_mode.
ModeSkill LoadedDescription
subagent-driven-developmentSuperpowers subagent-driven-developmentAI spawns subagents for parallel task execution — best for independent tasks, high complexity, or changes requiring two-phase review
executing-plansSuperpowers executing-plansSingle-agent sequential execution — lightweight and fast; requires a code review gate before the phase closes
direct(none — bypass)Single-agent direct execution without a plan skill; only the default for hotfix/tweak presets. Full-workflow changes require an explicit direct_override: true flag, otherwise the guard blocks the transition
direct mode in full workflow: To use direct mode outside of a hotfix or tweak preset, you must explicitly opt in. The AI will record direct_override: true in .comet.yaml — without it, both the guard and the build→verify state transition will block. This is intentional: full-workflow changes are expected to go through a proper plan execution skill.

​
Plan File

The plan is saved to docs/superpowers/plans/YYYY-MM-DD-<feature>.md and linked in .comet.yaml as the plan field. It contains:
  • A reference to the Design Doc
  • A breakdown of all implementation tasks
  • The base-ref git commit SHA used by the verify phase to measure change scope

​
The plan-ready Pause

build_pause: plan-ready is a recoverable pause point, not a build mode. It records that the plan has been generated and the AI has stopped — waiting for you to resume, possibly in a different model or session. When you run /comet or /comet-build again, Comet reads the existing plan and picks up from the isolation/execution-mode selection step. The plan is never regenerated on resume.
Commit frequently. One commit per task is the Comet convention — it creates a traceable history where each commit maps to a specific task and design decision. This also makes the verify phase more reliable: the base-ref + commit range gives an accurate picture of everything that changed.

​
Spec Incremental Updates

Specs evolve during implementation. When you discover the initial spec is incomplete mid-build, handle it based on scale:
ScaleWhenWhat to Do
SmallMissing acceptance scenarios, edge casesEdit the delta spec and design.md directly; append tasks to tasks.md
MediumInterface changes, new components, data flow changesThe AI pauses for your confirmation, then loads the Superpowers brainstorming skill to update the Design Doc and delta spec together
LargeBrand-new capability requirementsThe AI pauses and asks you to confirm splitting into a new, independent change started via /comet-open
50% threshold rule: If new tasks would exceed half of the original task count in tasks.md, the change is considered outside its original scope. The AI must pause and ask whether you want to split the work into a new change — it cannot continue expanding the current change automatically. When creating a new change from within build, always invoke /comet-open (not any OpenSpec command directly) to ensure the new change gets its own .comet.yaml and enters the state machine correctly. Principles for keeping specs current:
  • The delta spec is a living document — edit it freely during build whenever the implementation evolves
  • Commit each spec edit with a message explaining the change reason, so design doc drift can be assessed during archiving
  • Never sync delta specs to main specs during build — that happens only at archive, once the change is fully verified

​
Guard Enforcement

Before the build phase can advance to verify, the guard enforces two hard requirements:
  • isolation must be set to branch or worktree
  • build_mode must be set to a valid value (subagent-driven-development, executing-plans, or direct with direct_override: true)
If either field is null, the guard blocks the transition and reports which field is missing.

​
Context Compaction and Recovery

The build phase is the longest in the workflow and may span many tasks across multiple sessions. Comet is designed to survive context compaction:
  • After each task: the AI marks the checkbox in tasks.md and commits code immediately — this makes .comet.yaml and file state durable across any session boundary.
  • After context compaction: run the recovery command to get a structured summary of isolation method, build mode, plan path, task progress, and the recommended next action:
"$COMET_BASH" "$COMET_STATE" check <change-name> build --recover
  • Single task too large: if one task would exceed ~200 lines of code changes, split it into subtasks with separate commits to keep the history granular.