comet-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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.**

```bash
"$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`:

```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

The beta handoff package is a **structured spec projection** that reduces OpenSpec token load without replacing the canonical spec:
- `spec-context.json`: machine index containing change, phase, canonical spec, source paths, hash, and file roles
- `spec-context.md`: context for Superpowers to read, verbatim-projecting delta spec files and referencing supporting artifacts by hash
- OpenSpec delta specs remain canonical; if the projection is missing, stale, or unclear, regenerate the handoff or read the source spec directly instead of writing an agent summary

If full context is genuinely needed, explicitly run:

```bash
"$COMET_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. Skipping this step is prohibited.

When loading the skill, ARGUMENTS must include:

```text
Language: Use the language of the user request that triggered this workflow
```

After the skill loads, follow its guidance and use the following context:

```
Change: <change-name>
OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json

If context_compression is beta, use:
OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/spec-context.md
Machine handoff: openspec/changes/<name>/.comet/handoff/spec-context.json

OpenSpec artifacts are the upstream source of truth, but you must not weaken the Superpowers `brainstorming` clarification flow by "skipping redundant context exploration".
Your task is to perform deep technical design based on the handoff package: implementation approach, technical risks, testing strategy, boundary conditions.
If goals, scope, non-goals, acceptance scenarios, or key constraints remain unclear, you must continue asking questions and form the design proposal first; must not create the Design Doc after only one Q&A turn.
Do not rewrite proposal/spec; 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. Spec Patches are limited to supplementing acceptance scenarios, correcting ambiguous descriptions, or adding boundary conditions — they must not substantially rewrite the delta spec's structure or scope. If major changes are needed, flag them as design findings and return to brainstorming for confirmation.

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

Proceed through the original `brainstorming` skill flow: clarifying questions, 2-3 approaches, and step-by-step design confirmation. Do not write the Design Doc early.
```

Proceeding without loading this skill is prohibited.

If the Superpowers `brainstorming` skill is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.

From rpamis/comet, MIT.

More from rpamis/comet