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"
"$COMET_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.

"$COMET_BASH" "$COMET_HANDOFF" <change-name> 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:

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

Beta mode (context_compression: beta in project .comet/config.yaml, snapshotted into .comet.yaml when the change is created) generates:

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

And writes to .comet.yaml:

handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
handoff_hash: <sha256>