comet-design

name	comet-design
description	Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Design Doc and delta spec through brainstorming.

Comet Phase 2: Deep Design (Design)

Prerequisites

• Active change exists (proposal.md, design.md, tasks.md)
• No Design Doc (no corresponding file under docs/superpowers/specs/)

Steps

0. Entry State Verification (Entry Check)

Execute entry verification:

COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
if [ -z "$COMET_ENV" ]; then
  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
  return 1
fi
. "$COMET_ENV"
bash "$COMET_STATE" check <name> 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" <change-name> design --write

The script generates and records:

openspec/changes/<name>/.comet/handoff/design-context.json
openspec/changes/<name>/.comet/handoff/design-context.md

And writes to .comet.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:

• 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

If full context is genuinely needed, explicitly run:

bash "$COMET_HANDOFF" <change-name> 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, ARGUMENTS containing:

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 artifacts are the upstream source of truth. Do not redefine requirements, do not rewrite proposal/spec.
Your task is to perform deep technical design based on the handoff package: implementation approach, technical risks, testing strategy, boundary conditions.
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.

Design Doc frontmatter must be minimal, containing only:
---
comet_change: <change-name>
role: technical-design
canonical_spec: openspec
---

Skip redundant context exploration, proceed directly to design questions.

Skipping this step is prohibited. Proceeding without loading this skill is prohibited.

If superpowers:brainstorming 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
• 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-<topic>-design.md be created and delta spec written back.

1c. User Confirms Design Proposal (Blocking Point)

After brainstorming produces a design proposal, must use the AskUserQuestion tool 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. Must not just output a text prompt and then continue executing.

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.

2. Update Comet State

First record the design_doc path. If Step 1c wrote back delta spec (added or modified specs/*/spec.md), must regenerate handoff to update hash:

# Record design_doc path
bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md

# If delta spec changes exist, regenerate handoff (update hash)
bash "$COMET_HANDOFF" <change-name> design --write

# Auto-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 updates automatically; no manual editing of other fields needed.

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 must be script-generated and contain source path, mode, sha256 traceability markers (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 bash "$COMET_GUARD" <change-name> design --apply; after all PASS, auto-transitions to phase: build

Must use --apply before exit:

bash "$COMET_GUARD" <change-name> design --apply

Context Compaction Recovery

The design phase may trigger context compaction during brainstorming. To recover, first run:

bash "$COMET_STATE" check <change-name> design --recover

The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the Recovery action to determine next step.

Automatic Transition

After exit conditions are met (including user confirming the design proposal), auto-transition to next phase:

REQUIRED NEXT SKILL: Invoke comet-build skill to enter the plan and build phase.