Skip to main content
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.

​
Trigger

Run /comet-design directly, or let /comet auto-dispatch after Phase 1 completes.

​
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

1

Generate the OpenSpec → Superpowers handoff package

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.
2

Brainstorming explores the technical problem

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.
3

You confirm the design proposal (blocking pause)

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.
4

Design Doc is written

Once you confirm, the AI creates the Design Doc at docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md. The file’s frontmatter is minimal by design:
---
comet_change: <change-name>
role: technical-design
canonical_spec: openspec
---
This links the Design Doc back to the OpenSpec change without duplicating requirements.
5

Delta spec is created or updated

If brainstorming identified missing acceptance scenarios or new capabilities, the OpenSpec delta spec at openspec/changes/<name>/specs/<capability>/spec.md is created or updated with Spec Patches. The handoff hash is regenerated to reflect the updated artifacts.
6

State is updated and guard advances the workflow

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

ArtifactPathDescription
Design Docdocs/superpowers/specs/YYYY-MM-DD-<topic>-design.mdTechnical RFC — implementation approach, trade-offs, testing strategy
Delta specopenspec/changes/<name>/specs/<capability>/spec.mdAcceptance scenarios and capability spec for this change
Handoff context (JSON)openspec/changes/<name>/.comet/handoff/design-context.jsonMachine-readable handoff index with SHA256 hash
Handoff context (Markdown)openspec/changes/<name>/.comet/handoff/design-context.mdHuman-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: 
"$COMET_BASH" "$COMET_HANDOFF" <change-name> 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: 
"$COMET_BASH" "$COMET_STATE" check <change-name> 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.