Comet Phase 3: Plan and Build

On first entering a phase, handing off to a new Agent, or restoring context, read and follow Task Context and Artifact Language. Prefer the current continuation or claimed Action's contextRequest; do not retrieve repeatedly during uninterrupted work in the same phase.

After entry returns layout, follow comet-classic/reference/classic-layout.md to bind each logical root to its directory. Do not reload the protocol if it is already in context. Use the adapter for all OpenSpec CLI calls and the bound <classic-*> roots for paths; do not run an extra root show first.

When an edit needs an actual-impact judgement or a continuation points to a content judgement, you must read and follow edit continuation. The current Agent merges the handling of changes, keeps the original Run, valid approvals, and checks, and adds only evidence for what is affected.

SDK Run path

On first entering the current SDK phase, handing off to a new Agent, or restoring context, read phase entry and recovery and the current phase's section in that reference. Reuse them when already available and still valid in this session. Continue with the phase below; recovery routes based on nextAction.kind apply only to older responses without a continuation mode.

Reuse the current valid result's agent.continuation / data.nextAction and bound state. Run comet state next <change-name> --json only on a cold resume, after external state changes, or when necessary information is missing. For data.runtimeFormat: sdk, advance only this Run; the implementation methods, plan content, and reviews are in SDK execution methods; submit state and evidence through this section. data.phase must be build. Reuse valid layout and configuration already in context; use comet state check <change-name> build --json only when they are missing. For nextAction.kind: reconcile, run comet state check <change-name> build --recover --json and establish the original outcome before repeating external work.

First check workflow in the valid configuration or the current nextAction.stepId. For tweak.build.* / workflow: tweak, Immediately execute: Use the Skill tool to load the comet-tweak skill. Skipping this step is prohibited. For hotfix.build.* / workflow: hotfix, Immediately execute: Use the Skill tool to load the comet-hotfix skill. Skipping this step is prohibited. After the skill loads, pass the same change, workspace, phase, Run revision, and continuation and resume its SDK Build step. Do not require a full Design Doc or implementation plan, or repeat Open. Older Runs may still store comet-build as the raw Action reference; route them the same way. After an approved upgrade, use the full path in SDK execution methods when the current step is full.build.*.

1. At full.build.configure, present values, meanings, and confirmation status under Build configuration guidance. Ask only for missing, invalid, or explicitly changed decisions about execution, TDD, and review. Put confirmed build_mode, tdd_mode, review_mode, subagent_dispatch, and, when required, direct_override in a temporary JSON file inside the repository. If the user already explicitly chose this complete configuration, run comet state propose-build <change-name> --file <configuration-json> --confirmed to save proposal and approval together. Otherwise run comet state propose-build <change-name> --file <configuration-json>. Only for a remaining pending Wait, save data.wait.proposalHash, show the actual configuration, and await confirmation under decision-point.md. Then run comet state decide-build <change-name> --proposal-hash <proposalHash> --choice <approved|rejected>. Propose revised choices after rejection. Reuse an existing pending Wait on recovery without asking again or creating another configuration Action. After saving approval, briefly echo the result and continue without another confirmation to proceed.
2. At full.build.plan, create or inspect the plan under SDK execution methods. Refer to the current Design Doc and tasks.md, mapping tasks with <!-- comet-task-authority: <classic-task-authority-ref> --> and <!-- comet-task-ref:<task-id> -->, not another checkbox list. Run comet state submit-plan <change-name> --plan <plan-ref>. Add --pause only if the user explicitly requested a pause after planning. For a plan-ready Wait, await an explicit instruction to proceed and use its current hash in comet state continue-plan <change-name> --proposal-hash <proposalHash>. Do not reuse approval after plan or task requirements change.
3. At full.build.execute, implement using the chosen method, review tasks or segments, and run relevant checks. Check off the same tasks.md only after actual completion and satisfactory review. Use the shared state tasks, state task-complete, and state checkpoint tools for task IDs, completion, and coordination progress; they do not advance the SDK Run. SDK must not call legacy comet handoff --write. Once plan, tasks, and workspace agree, run comet state complete-build <change-name> --session <builder-execution-ref> to enter the check Action. Resolve drift before submission.
4. At full.build.check, run comet guard <change-name> build --apply -- <program> [args...] with an explicit complete build or acceptance command for this workspace. There is no new user decision here: --apply revalidates current tasks, configuration, workspace, and evidence before executing the check and recording a receipt in the same Run. Only valid successful evidence advances to Verify. Use the read-only comet guard <change-name> build preview only when diagnosis is needed. After interrupted receipt submission, investigate the Action and check record before re-executing anything. On failure, repair the cause from the returned current Build Action; read state next --json only when no continuation was returned.

After each advance, use that result's agent.continuation / data.nextAction. Do not repeat next, select, or check while state is valid and complete; read again only on a cold resume, after external state changes, or for missing information. Load the next Skill only for an action in the next phase; resolve decision, evidence, and reconcile within the current Run. For deterministic local checks, add --local before -- as described in SDK execution methods; Runtime validates full inputs and logs before reuse. External checks still execute. Associate SDK Build with a stable --session ; full complete-build already carries it when supplied.

Compat path

The remaining original Runtime steps apply only to runtimeFormat: compat. Read Compat operations and continue its current phase. SDK does not load that reference.

Optional change walkthrough

At Build completion and before presenting Verify results, check the project .comet/config.yaml field change_walkthrough (enabled by default; only explicit false disables it). When enabled, read and execute Change walkthrough, use the shared template to generate or update the same walkthrough.html, and provide an opening link. When disabled, skip extra explanation, detailed instructions and rendering; retain the existing summary. Archive preserves existing pages with the materials and links to their actual archived location; it does not generate missing pages, add confirmation or rerun code checks for page updates.