--- name: comet-design description: "Phase 2 of Comet Classic — produce the deep technical Design Doc behind a change." disable-model-invocation: true --- # Comet Phase 2: Deep Design (Design) Before starting or recovering, read and follow `comet-classic/reference/classic-layout.md`. Every OpenSpec CLI call in this file must use the adapter, and every file path must use the `` logical roots bound by that protocol. ## Prerequisites - Active change exists (proposal.md, design.md, tasks.md) - No Design Doc (no corresponding file under `docs/superpowers/specs/`) > Responsibility boundary: the open-phase `design.md` gives the **high-level solution framework** (architecture decision direction, approach selection, data flow); the design-phase Design Doc is its **deep technical refinement** (detailed implementation design, technical risks, test strategy, edge cases) — a deepening, not a replacement or rewrite. ## Steps ### 0. Entry State Verification (Entry Check) Locate scripts via `comet-classic/reference/scripts.md`, then run entry verification. When resuming from any entry point, first run the recovery check in `comet-classic/reference/context-recovery.md`: ```bash comet state select comet state check design ``` Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails. **Idempotency**: All design phase operations can be safely re-executed. If `handoff_context` and `handoff_hash` already exist, confirm they match current artifacts before deciding whether to regenerate. ### 1a. Generate OpenSpec → Superpowers Handoff Package **Must be generated by script. Agent writing summaries on the fly is not allowed.** ```bash comet handoff design --write ``` The script reads the change `.comet.yaml` `context_compression` snapshot, then generates and records the matching handoff package. Default `context_compression: off` generates: ``` /.comet/handoff/design-context.json /.comet/handoff/design-context.md ``` Beta mode (`classic.context_compression: beta` in project `.comet/config.yaml`, snapshotted into `.comet.yaml` when the change is created) generates: ``` /.comet/handoff/spec-context.json /.comet/handoff/spec-context.md ``` And writes to `.comet.yaml`: ```yaml handoff_context: /.comet/handoff/design-context.json handoff_hash: ``` The default handoff package is a **compact traceable excerpt**, not an agent summary: - `design-context.json`: machine index containing change, phase, canonical spec, source paths, hash - `design-context.md`: context for Superpowers to read, containing script markers, source path, line range, sha256, deterministic excerpts - When exceeding excerpt budget, marks `[TRUNCATED]` and retains Full source path The beta handoff package is a **structured spec projection** that reduces OpenSpec token load without replacing the canonical spec: - `spec-context.json`: machine index containing change, phase, canonical spec, source paths, hash, and file roles - `spec-context.md`: context for Superpowers to read, verbatim-projecting delta spec files and referencing supporting artifacts by hash - OpenSpec delta specs remain canonical; if the projection is missing, stale, or unclear, regenerate the handoff or read the source spec directly instead of writing an agent summary If full context is genuinely needed, explicitly run: ```bash comet handoff design --write --full ``` Handoff package sources come from OpenSpec open phase artifacts: - `proposal.md`: goals, motivation, scope, non-goals - `design.md`: high-level architecture decisions, approach constraints - `tasks.md`: initial task boundaries - `specs/*/spec.md`: delta capability specs ### 1b. Execute Brainstorming (with Context) **Immediately execute:** Use the Skill tool to load the Superpowers `brainstorming` skill. Skipping this step is prohibited. When loading the skill, ARGUMENTS must include: ```text Language: Use the configured Comet artifact language from `comet state get language` ``` After the skill loads, follow its guidance and use the following context: ``` Change: OpenSpec Context Pack: /.comet/handoff/design-context.md Machine handoff: /.comet/handoff/design-context.json If context_compression is beta, use: OpenSpec Context Pack: /.comet/handoff/spec-context.md Machine handoff: /.comet/handoff/spec-context.json OpenSpec artifacts are the upstream source of truth, but you must not weaken the Superpowers `brainstorming` clarification flow by "skipping redundant context exploration". Your task is to perform deep technical design based on the handoff package: implementation approach, technical risks, testing strategy, boundary conditions. If goals, scope, non-goals, acceptance scenarios, or key constraints remain unclear, you must continue asking questions and form the design proposal first; must not create the Design Doc after only one Q&A turn. Do not rewrite proposal/spec; if you find OpenSpec delta spec missing acceptance scenarios, you may only propose Spec Patches and write them back to OpenSpec delta spec; do not create a second requirements spec in the Design Doc. Spec Patches are limited to supplementing acceptance scenarios, correcting ambiguous descriptions, or adding boundary conditions — they must not substantially rewrite the delta spec's structure or scope. If major changes are needed, flag them as design findings and return to brainstorming for confirmation. Design Doc frontmatter must be minimal, containing only: --- comet_change: role: technical-design canonical_spec: openspec --- Proceed through the original `brainstorming` skill flow: clarifying questions, 2-3 approaches, and step-by-step design confirmation. Do not write the Design Doc early. ``` Proceeding without loading this skill is prohibited. If the Superpowers `brainstorming` skill is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation. After the skill loads, follow its guidance to produce design proposals (presented as conversation): - Technical approach: architecture, data flow, key technology choices and risks - Testing strategy - Requirement/scope gaps and Spec Patches to be written back - If acceptance scenarios need supplementing, indicate delta spec changes to be written back The brainstorming phase does not write to the Design Doc file; it only produces design proposals for Step 1c user confirmation. Only after confirmation should `docs/superpowers/specs/YYYY-MM-DD--design.md` be created and delta spec written back. For context compaction recovery, the agent must incrementally update `brainstorm-summary.md` during brainstorming. After each clarification round or proposal iteration, update the file whenever new confirmed facts, key constraints, candidate approaches, trade-offs/risks, testing strategy, or Spec Patch candidates emerge; mark unconfirmed items as "pending" or "candidate". This file is a recovery checkpoint, not the Design Doc, and must not replace the Step 1c user confirmation. ### 1c. User Confirms Design Proposal (Blocking Point) After brainstorming produces a design proposal, **must follow the `comet-classic/reference/decision-point.md` protocol to pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation. When pausing, only present essential summary: - Technical approach adopted - Key trade-offs and risks - Testing strategy - If there are Spec Patches, list the delta spec changes to be written back Only after the user explicitly confirms, proceed to Step 2. If the user requests adjustments, continue brainstorming iteration until the user confirms. ### 1d. Brainstorming Checkpoint Finalization After the user confirms the design proposal, before creating the Design Doc, create or update the incrementally maintained checkpoint file and finalize it as the confirmed design summary: Use the file tool to ensure `/.comet/handoff/` exists; do not rely on a POSIX-only directory command. `/.comet/handoff/brainstorm-summary.md` structure: ```markdown # Brainstorm Summary - Change: - Date: ## Confirmed Technical Approach ## Key Trade-offs and Risks ## Testing Strategy ## Spec Patches ``` **Context compaction note**: Each incremental update to `brainstorm-summary.md` is a relatively safe recovery point. After brainstorming completes, if the context window is tight, prefer compacting here. After compaction, reload the following files to continue Step 2: - `/.comet/handoff/brainstorm-summary.md` - `/.comet/handoff/design-context.md` (or `spec-context.md` in beta mode) - `/.comet/handoff/design-context.json` (or `spec-context.json` in beta mode) ### 1e. Compaction Policy (Non-blocking Here) `brainstorm-summary.md` is a recovery checkpoint, but do not discard live design context before the Design Doc is persisted. Continue directly to Step 2. Active compaction moves until after the Design Doc, state, and latest handoff are all durable. ### 2. Create Design Doc Create the Design Doc based on the full brainstorming conversation context (still in the main session). Design Doc frontmatter must be minimal: ```yaml --- comet_change: role: technical-design canonical_spec: openspec --- ``` Write the Design Doc to `docs/superpowers/specs/YYYY-MM-DD--design.md`. If Spec Patches need to be written back, also edit the corresponding `specs/*/spec.md`. **Context compaction recovery**: If context has been compacted, resume from `brainstorm-summary.md` + handoff context. If the user has not confirmed the design proposal yet, return to Step 1b/1c and continue brainstorming; if the user has confirmed it, continue creating the Design Doc. brainstorm-summary.md is the compaction checkpoint, not the sole input for the Design Doc — when creating, leverage the full recovered context as much as possible. ### 3. Update Comet State First record the design_doc path. If Spec Patches wrote back delta spec (added, modified, or removed `specs/*/spec.md`), must regenerate handoff to update hash: ```bash # Record design_doc path comet state set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md # If delta spec changes exist, regenerate handoff (update hash) comet handoff design --write # Auto-transition to next phase comet guard design --apply ``` Adding, modifying, or removing a delta spec changes the handoff hash, so deleting a delta spec also requires regenerating the handoff; otherwise the recorded `handoff_hash` no longer matches the current OpenSpec artifacts and the design guard blocks progress. If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed. ### 3a. Optional Active Context Compaction Consider active compaction only **after the Design Doc and state evidence are persisted** and before Build. First confirm `design_doc`, the latest handoff, `handoff_hash`, and the design guard are durable so recovery never depends on an unwritten design judgment. - When a programmatically callable compaction mechanism is present and the context window is under pressure, invoke it once and include the change, next step, Design Doc, and handoff files in the resume prompt - If compaction requires user action, give one non-blocking suggestion and continue; it **must not block** and must not create another confirmation point - Never fake compaction with a shell command or an agent summary ## Exit Conditions - Design Doc created and saved - Design Doc frontmatter contains `comet_change`, `role: technical-design`, `canonical_spec: openspec` - `handoff_context` and `handoff_hash` written to `.comet.yaml` (enforced by guard) - `handoff_hash` matches current OpenSpec open phase artifacts (enforced by guard) - `design-context.md` or beta `spec-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard) - In beta mode, `spec-context.json` must be structurally valid and reference the current source files (enforced by guard) - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated - `design_doc` written to `.comet.yaml` - **Phase guard**: Run `comet guard design --apply`; after all PASS, auto-transitions to `phase: build` Must use `--apply` before exit: ```bash comet guard design --apply ``` ## Context Compression Recovery Follow `comet-classic/reference/context-recovery.md` with phase set to `design`. ## Automatic Handoff to Next Phase Follow `comet-classic/reference/auto-transition.md`. Key command: ```bash comet state next ``` - `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase - `NEXT: manual` → do not invoke the next skill; return control with `HINT`, end the invocation, and do not create another confirmation point - `NEXT: done` → workflow is complete, no further action needed