Comet Build

Comet Phase 3: Plan and Build

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.

Prerequisites

• The Design Doc exists; Phase 2 is complete.
• An active change exists.

Steps

0. Validate entry state

Use the supported comet CLI described in comet-classic/reference/scripts.md for these checks. When resuming from any entry, first follow comet-classic/reference/context-recovery.md:

comet state select <change-name>
comet state check <name> build --json

If this invocation already has a successful Design/Guard result with Build state, use its data.configuration, configurationReadiness, artifactRefs, task information, and agent.continuation without repeating select/check. Run the entry commands above only on recovery or workspace/external state changes. After writing configuration, use the successful result rather than repeating get for every field. Handle data.issues on failure.

If select/check returns BLOCKED — or a branch-binding ERROR — because bound_branch differs from the current branch, pause under comet-classic/reference/decision-point.md. Offer a single choice: return to the bound branch and rerun entry checks, or, after the user explicitly confirms that the current branch should take over this change, run comet state rebind <change-name> and rerun entry checks. Do not switch or rebind branches yourself.

Recovery: Reconcile the returned phase, task IDs, and plan base-ref with existing implementation and review records. Resume the unfinished implementation or review step. An unchecked task may already be implemented. Inspect checkpoints before dispatching; do not repeat existing commits or assume external operations are safe to retry.

1. Confirm the execution strategy first

Read configuration, configurationReadiness, taskState, and nextAction from entry. When configurationReadiness.missingFields and invalidFields are empty, retain the confirmed configuration instead of presenting the same choices again; ask only about the listed missing or invalid decisions. If configuration, plan, and review records remain valid, continue without asking again or regenerating them. Open must already have prepared and bound the workspace. Stop if isolation is missing or the directory does not match, and resume in the projectRoot returned by workspace resolve. Do not create or switch workspaces in Build.

Confirm the execution strategy before writing a plan. configurationReadiness lists only unresolved or invalid fields; a valid configuration is not presented as a new choice. If configuration is missing or the user explicitly requests a change, collect execution mode, TDD, and review mode together under comet-classic/reference/decision-point.md, asking only about the listed decisions. Do not choose based on the model name.

Recommend autonomous when the Agent can plan effectively and a long task needs flexible organization. Recommend subagent-driven-development for a fixed delegation method, or executing-plans for a fixed sequential method. Recommendations do not replace user confirmation and must not automatically replace an existing change's strategy.

Full autonomous requires standard or thorough; implementer self-review cannot replace independent review. Existing execution strategies retain their review_mode rules. Recommend tdd and standard by default. Hotfix/tweak direct presets remain unchanged.

After the user makes all choices, write the configuration atomically. For example, for an explicit autonomous/TDD/standard choice:

comet state set <name> build_mode autonomous subagent_dispatch null tdd_mode tdd review_mode standard --json

Substitute the actual choices. For subagent-driven-development, also write subagent_dispatch confirmed; for other modes, write null. Preserve isolation, bound_branch, and any existing pause. Stop on write failure without loading the execution skill. If the user has not decided or requests a pause, stop without writing partial configuration.

direct is not an alias for autonomous. Full allows direct only when explicitly requested and recorded with direct_override true. Autonomous does not permit skipping design, planning, configuration, verification, or independent review.

2. Create or resume the plan

tasks.md determines task completion. Run comet state tasks <name> --json only when task bodies or IDs are needed. If IDs are missing, run comet state tasks <name> --assign-ids --json, preserving existing IDs and updating affected handoff content and plan mappings.

Follow context-recovery.md when resuming, syncing legacy plan checkboxes, or recording completed work. Unchecked does not mean unimplemented: check off work whose implementation, checks, and reviews are sufficient, and finish only what remains for other tasks. task-complete automatically syncs legacy plans with comet-task ID mappings. Use comet state sync-plan <name> for a separate sync. When planSync returns mapping-required, add the mapping without reimplementing the task.

Keep an existing valid plan. Otherwise, use configuration.language to create <classic-superpowers-root>/plans/<YYYY-MM-DD>-<change-name>.md:

• autonomous: the current Agent writes and checks the plan directly, without loading writing-plans.
• Other plan execution strategies: use the writing-plans skill for writing and self-checking only; stop if it fails. Pass the confirmed configuration, design_doc, tasks.md, fixed plan path, and current git rev-parse HEAD. Return to Comet Build afterwards without choosing the strategy again or entering the external skill's subsequent workflow.

Adjust plan depth to risk: keep plans brief for clear, mature, reversible work; record tradeoffs, dependencies, rollback, and verification for real technical choices, component dependencies, permissions, migrations, concurrency, compatibility, or irreversible operations. Each task must still produce an independently acceptable result and identify its task ID, scope, dependencies, constraints, and acceptance commands or scenarios. Organize preparation, implementation, tests, and documentation around that result. Do not split tasks by estimated minutes, file counts, or RED/GREEN steps. Reference designs and requirements rather than writing the whole implementation in advance. Include code excerpts only for interfaces or high-risk algorithms that need review before implementation.

Do not create another checkbox list in a new plan. Add <!-- comet-task-authority: <classic-task-authority-ref> -->, using the repository-relative reference from data.artifactRefs.tasks, and associate each task with <!-- comet-task-ref:<task-id> -->. Add actual new work to tasks.md and assign IDs before adding it to the plan. Handle scope changes under Step 4.

Plan frontmatter:

---
change: <change-name>
design-doc: <recorded-design-doc-path>
base-ref: <git rev-parse HEAD before implementation>
---

Keep a legacy plan's base-ref; do not replace it with current HEAD on recovery. Reuse data.artifactRefs.plan for <plan-ref>. For a new plan, combine data.artifactRefs.plansRoot and the chosen filename into a repository-relative reference. Use the absolute path only for writing. After confirming that the file exists, record it:

comet state set <name> plan "<plan-ref>" --json

Continue under the confirmed strategy after planning; do not add another configuration approval. If the user explicitly requests a model switch or a pause after the plan, write comet state set <name> build_pause plan-ready and stop. Clear an existing plan-ready pause only after the user explicitly asks to continue. Keep the valid plan and configuration. For an older change missing configuration, complete Step 1 without rewriting the plan.

3. Implement and accept tasks

Use this invocation's entry configuration and continuation before implementation. Refresh entry after configuration, requirements, or workspace changes. Run checks according to risk instead of repeating the full suite after every small edit. External skills execute only the current plan and confirmed configuration. They must not create a worktree, choose isolation again, add a final review, or call finishing-a-development-branch. Return completed tasks to Comet Build.

• autonomous: organize implementation within the plan. Before delegation, read comet-classic/reference/subagent-dispatch.md, delegate a clearly scoped group of tasks as a work package, save coordination records through Runtime, and arrange an independent reviewer. External execution skills are not mandatory.
• executing-plans: load Superpowers executing-plans with the Skill tool, pass entry configuration.language, and execute the plan in order. Stop if loading fails.
• subagent-driven-development: load the same-named Superpowers skill and comet-classic/reference/subagent-dispatch.md. The main session coordinates without writing code on the implementer's behalf. If dispatch fails, save the BLOCKED reason; do not silently take over or change strategies.

With tdd, every implementation task must record actual RED and corresponding GREEN commands/results, with a RED failure caused by the intended missing behavior. Autonomous need not load an external TDD skill but still requires RED/GREEN. Executing-plans loads test-driven-development once before first implementation; the implementer loads it for subagent execution. Do not reload while context is intact. After context loss, inspect existing results instead of reenacting verified implementation or reverting code to fabricate RED. Direct still requires relevant checks and defect regression results.

Build reviews tasks or sections only; Verify owns the single final integration review:

• Autonomous and subagent execution: follow the risk levels and review-attempt limits in subagent-dispatch.md for independent task reviews. Even when autonomous does not delegate implementation, required review must be independent.
• executing-plans + off|standard: accept tasks and enter Verify without an additional final Build review.
• executing-plans + thorough: every task must receive independent review. Closely dependent tasks that must be accepted together may form a section. Review the diff by independently acceptable result and risk, not a fixed number of tasks. Review each section before continuing implementation that depends on it. Do not combine all independently acceptable tasks to delay review until the end. The last section, with no further implementation depending on it, is reviewed by Verify's single final integration review.

Resolve CRITICAL/IMPORTANT findings. Stop if independent review is unavailable; self-review is not a substitute. Record the rationale and affected scope of accepted noncritical deviations. After acceptance, use task-complete to check off tasks.md by ID. Save coordination and recovery records through comet state checkpoint <name> --file <json-path>; see context-recovery.md for fields and read/write rules. Checkpoints do not replace task completion marks or actual check/review results.

3b. Diagnose unexpected execution failures

Investigate the root cause of unexpected crashes, behavior, test failures, or build failures before changing source. Autonomous follows the debugging protocol directly; other strategies load Superpowers systematic-debugging. A verified TDD RED caused by the missing behavior is expected evidence. Loading errors, environment errors, unrelated regressions, and unexplained RED failures still require investigation.

Follow comet-classic/reference/debug-gate.md for root-cause investigation, a minimal failing test, verification after repair, and completing these steps within the current change.