> ## Documentation Index > Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt > Use this file to discover all available pages before exploring further. # Phase 2: Deep Design — Brainstorming and Design Doc > The Design phase uses Superpowers brainstorming to create a Design Doc and delta specs — a mandatory deep-design step for every full-workflow change. The Design phase is where OpenSpec hands off to Superpowers. After your change structure is confirmed in Phase 1, `/comet-design` generates a handoff package from your Phase 1 artifacts and loads the Superpowers brainstorming skill to perform deep technical exploration — working through implementation approaches, risks, trade-offs, and testing strategy. Only after you explicitly approve the design proposal does it write the final Design Doc and advance the workflow. This page uses `` for the configured Classic OpenSpec root: `docs/openspec/` for new projects and `openspec/` for projects that retain the legacy layout. The location is selected by `classic.artifact_layout`; see [Project file structure](/en/guides/project-structure). ## Trigger Normally, invoke `/comet`. When configuration selects Classic, the internal `/comet-classic` router reads state and dispatches `/comet-design` after Phase 1 completes. Invoke the phase Skill directly only for manual control. ## Owner **OpenSpec and Superpowers** — OpenSpec generates the handoff package from Phase 1 artifacts; Superpowers brainstorming drives the technical exploration and produces the Design Doc. **Brainstorming cannot be skipped.** For full-workflow changes, the Superpowers `brainstorming` skill is mandatory — it cannot be replaced by a quick summary or normal conversation. The only exceptions are the **hotfix** and **tweak** presets, which bypass Phase 2 entirely and go directly to build. If the brainstorming skill is unavailable, the workflow stops and prompts you to install or enable Superpowers skills. ## What Happens Before brainstorming begins, `comet-handoff.sh` generates a deterministic context package from the Phase 1 artifacts. This produces two files and writes their paths and a SHA256 hash to `.comet.yaml`: * `design-context.json` — machine-readable index (change, phase, canonical spec, source paths, hash) * `design-context.md` — human-readable context Superpowers reads during brainstorming, with source path markers, line ranges, and SHA256 traceability The handoff is script-generated — the AI cannot write it manually. This ensures Superpowers receives a verified, traceable snapshot of what OpenSpec actually contains. The AI loads the Superpowers `brainstorming` skill with the handoff package as context and begins deep technical exploration: * Implementation approach: architecture, data flow, key technology choices * Trade-offs and risks for each option * Testing strategy * Any acceptance scenarios missing from the OpenSpec delta spec (proposed as Spec Patches, not rewritten requirements) Brainstorming is conversational — the AI presents proposals and iterates with you. The Design Doc file is **not written yet** at this stage. After brainstorming produces a design proposal, the AI pauses and presents a concise summary: * The technical approach adopted * Key trade-offs and risks * Testing strategy * Any delta spec changes to be written back **The workflow cannot advance until you explicitly confirm.** If you request adjustments, brainstorming continues until you confirm. Once you confirm, the AI creates the Design Doc at `docs/superpowers/specs/YYYY-MM-DD--design.md`. The file's frontmatter is minimal by design: ```yaml theme={null} --- comet_change: role: technical-design canonical_spec: openspec --- ``` This links the Design Doc back to the OpenSpec change without duplicating requirements. If brainstorming identified missing acceptance scenarios or new capabilities, the OpenSpec delta spec at `/changes//specs//spec.md` is created or updated with Spec Patches. The handoff hash is regenerated to reflect the updated artifacts. The `design_doc` path is recorded in `.comet.yaml`. If delta spec changes occurred, the handoff package is regenerated to keep the hash current. The phase guard then validates all exit conditions — including that `handoff_hash` matches current artifacts and `design-context.md` contains script-generated traceability markers — and auto-transitions to `phase: build`. ## Artifacts | Artifact | Path | Description | | -------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ | | Design Doc | `docs/superpowers/specs/YYYY-MM-DD--design.md` | Technical RFC — implementation approach, trade-offs, testing strategy | | Delta spec | `/changes//specs//spec.md` | Acceptance scenarios and capability spec for this change | | Handoff context (JSON) | `/changes//.comet/handoff/design-context.json` | Machine-readable handoff index with SHA256 hash | | Handoff context (Markdown) | `/changes//.comet/handoff/design-context.md` | Human-readable handoff context with source path and traceability markers | ## The Handoff Package `comet-handoff.sh` exists to solve a specific problem: AI agents summarizing context on the fly produce inconsistent, untraceable output. By generating the handoff deterministically from actual file content — with SHA256 hashes, source path markers, and line ranges — Comet ensures that Superpowers always works from a verified snapshot of what OpenSpec actually contains. The default package is a compact, traceable excerpt. If the full content of all source artifacts is genuinely needed, you can generate a full handoff explicitly: ```bash theme={null} "$COMET_BASH" "$COMET_HANDOFF" design --write --full ``` The `handoff_hash` stored in `.comet.yaml` is checked by the phase guard before the workflow can advance from design to build. If the hash doesn't match the current OpenSpec artifacts, the guard blocks the transition and reports a mismatch. ## Context Compaction Recovery The design phase can trigger context compaction during brainstorming. If that happens, run the recovery command to get a structured summary of what's been completed and what needs to happen next: ```bash theme={null} "$COMET_BASH" "$COMET_STATE" check design --recover ``` The script outputs the current phase, which fields are complete, which are still pending, and the recommended recovery action. Follow the recovery action to resume from the correct step.