Comet Phase 2: In-depth Design (Design)
Prerequisites
- An active change exists (proposal.md, design.md, tasks.md)
- No Design Doc exists (no corresponding file under )
Steps
0. Entry Check
Perform entry verification:
bash
COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> design
Proceed to Step 1 after verification passes. The script will output specific failure reasons if verification fails.
1a. Generate OpenSpec → Superpowers Handoff Package
Must be generated by script; agent-improvised summaries are not allowed.
bash
bash "$COMET_HANDOFF" <change-name> design --write
The script will generate and record:
openspec/changes/<name>/.comet/handoff/design-context.json
openspec/changes/<name>/.comet/handoff/design-context.md
yaml
handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
handoff_hash: <sha256>
The default handoff package is a compact, traceable excerpt, not an agent summary:
- : Machine index containing change, phase, canonical spec, source paths, hash
- : Context for Superpowers reading, including script markers, source path, line range, sha256, deterministic excerpts
- Mark when exceeding excerpt budget, and retain the Full source path
If full-text context is truly needed, explicitly run:
bash
bash "$COMET_HANDOFF" <change-name> design --write --full
The handoff package comes from OpenSpec open-phase outputs:
- : Goals, motivations, scope, non-goals
- : High-level architecture decisions, solution constraints
- : Initial task boundaries
- : Delta capability specifications
1b. Execute Brainstorming (with Context)
Execute immediately: Use the Skill tool to load the
superpowers:brainstorming
skill, with ARGUMENTS including:
Change: <change-name>
OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json
OpenSpec outputs are upstream factual sources; do not redefine requirements or rewrite proposal/spec.
Your task is to conduct in-depth technical design based on the handoff package: implementation plan, technical risks, testing strategy, boundary conditions.
If you find that the OpenSpec delta spec lacks acceptance scenarios, you can only propose a Spec Patch and write back to the OpenSpec delta spec; do not create a second requirement spec in the Design Doc.
Design Doc frontmatter must be minimal, containing only:
---
comet_change: <change-name>
role: technical-design
canonical_spec: openspec
---
Skip repeated context exploration and directly proceed to design questions.
Skipping this step is prohibited; do not proceed without loading this skill.
If
superpowers:brainstorming
is unavailable, stop the process and prompt to install or enable the Superpowers skill; do not use regular conversation as a substitute.
After loading the skill, produce the design plan in the form of dialogue as guided:
- Technical solution: Architecture, data flow, key technology selection and risks
- Testing strategy
- If acceptance scenarios need to be supplemented, mark the delta spec changes to be written back
No Design Doc file is written during the brainstorming phase; only the design plan is produced for user confirmation in Step 1c. Only after confirmation is
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
created and the delta spec written back.
1c. User Confirmation of Design Plan (Blocking Point)
After the brainstorming produces the design plan,
must pause and wait for explicit user confirmation of the design plan. Do not create the final Design Doc, write to
, run the design guard, or enter
before user confirmation.
Only display necessary summaries when pausing:
- Adopted technical solution
- Key trade-offs and risks
- Testing strategy
- If there is a Spec Patch, list the delta spec changes to be written back
Proceed to Step 2 only after explicit user confirmation. If the user requests adjustments, continue brainstorming iterations until confirmation is obtained.
2. Update Comet State
First record the design_doc path. If Step 1c wrote back to the delta spec (created or modified
), the handoff must be regenerated to update the hash:
bash
# Record design_doc path
bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
# If delta spec changed, regenerate handoff (update hash)
bash "$COMET_HANDOFF" <change-name> design --write
# Automatically transition to next phase
bash "$COMET_GUARD" <change-name> design --apply
If there are no delta spec changes, skip the handoff regeneration step. The state file is updated automatically; no need to manually edit other fields.
Exit Conditions
- Design Doc has been created and saved
- Design Doc frontmatter contains , ,
- and have been written to (enforced by guard validation)
- matches the current OpenSpec open-phase outputs (enforced by guard validation)
- must be generated by script and contain traceable markers such as source path, mode, sha256 (enforced by guard validation)
- If there are new capabilities or supplementary acceptance scenarios, the OpenSpec delta spec has been created/updated
- has been written to
- Phase Guard: Run
bash "$COMET_GUARD" <change-name> design --apply
bash
bash "$COMET_GUARD" <change-name> design --apply
Automatic Transition
After meeting the exit conditions, no need to wait for user input again, directly execute the next phase:
REQUIRED NEXT SKILL: Invoke the
skill to enter the planning and build phase.