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

Normally, invoke /comet. When configuration selects Classic, the internal /comet-classic router dispatches /comet-build after Phase 2 completes. If paused at build_pause: plan-ready, invoking /comet resumes without regenerating the plan; call /comet-build directly only for manual phase control.

​
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:
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 normally with /comet, or use /comet-build for manual phase control
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 continues on the current branch, 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. All three methods are available to full, hotfix, and tweak workflows and require an explicit user choice. Comet records the selected mode in isolation and the actual execution branch in bound_branch; later entry checks block accidental branch switches.

​
Build Modes

Your choice of build mode determines how the AI executes the plan. It is recorded in .comet.yaml as build_mode.
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. Resume normally with /comet; after configuration selects Classic, it reads the existing plan and continues from isolation/execution-mode selection. /comet-build remains available for manual phase control.
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: 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 current, branch, or worktree, and the current Git branch must match bound_branch
  • 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:
  • 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.
Last modified on July 22, 2026