Skip to main content
The Open phase is where every Comet workflow begins. Instead of jumping straight into code, /comet-open first explores the problem space with you using OpenSpec, produces three structured artifacts that define why you’re making a change, what the high-level approach looks like, and what tasks will be required — then pauses for your explicit approval before anything moves forward.

​
Trigger

Run /comet-open directly in your AI tool, or simply run /comet and let it detect that no active change exists and dispatch to the Open phase automatically.

​
Prerequisites

  • No active change (or you want to start a new one)
  • The Comet skill is installed (comet init has been run)

​
What Happens

1

Explore the problem space

The AI loads the openspec-explore skill and freely explores your idea — asking clarifying questions, mapping out goals and constraints, and summarizing the problem space. This step is mandatory and cannot be skipped.
2

Create the change structure

The AI loads openspec-new-change (or openspec-propose if your intent still needs shaping) to scaffold the change directory and produce the three core artifacts. The change name must come from you — Comet will ask if you haven’t already provided one.
3

Artifacts are written

Three documents and two state files are created under openspec/changes/<name>/:
  • proposal.md — the Why and What: problem background, goals, scope, and non-goals
  • design.md — high-level architecture decisions and approach selection
  • tasks.md — a checkbox task list ready for execution
  • .openspec.yaml — OpenSpec change metadata
  • .comet.yaml — Comet workflow state (initialized to phase: open)
4

Content completeness check

Before pausing for review, the AI confirms all three documents are non-empty and structurally complete. If any file is missing or empty, it fills the gap before proceeding.
5

You review and confirm (blocking pause)

The AI presents a summary of all three documents and asks you to confirm or request adjustments. The workflow cannot advance until you explicitly choose “Confirm.” If you request adjustments, the AI modifies the documents and re-presents them for confirmation.
6

Phase guard runs and state advances

Once you confirm, the phase guard validates all exit conditions and automatically transitions .comet.yaml to the next phase. Full-workflow changes proceed to phase: design; hotfix and tweak presets jump directly to phase: build.

​
Artifacts

FileLocationDescription
proposal.mdopenspec/changes/<name>/proposal.mdProblem background, goals, scope, and non-goals — the Why and What
design.mdopenspec/changes/<name>/design.mdHigh-level architecture decisions and approach selection — the How (overview)
tasks.mdopenspec/changes/<name>/tasks.mdCheckbox task list used to track implementation progress across all phases
.openspec.yamlopenspec/changes/<name>/.openspec.yamlOpenSpec change metadata and spec lifecycle state
.comet.yamlopenspec/changes/<name>/.comet.yamlComet workflow state — tracks phase, build mode, verification status, and more

​
User Decision Point

The Open phase has one blocking pause: after all three artifacts are created and pass the completeness check, the AI stops and presents a structured summary for your review. You must choose one of:
  • Confirm, proceed to next phase — artifacts meet expectations; the phase guard runs and the workflow advances
  • Needs adjustment — provide notes; the AI revises the documents and re-presents them for confirmation
The workflow will not advance automatically. This is your opportunity to correct scope, rename tasks, or reshape the approach before any deep design or code generation begins.

​
Naming Rule

The change name must come from you. Comet will never auto-generate or infer a name. If you don’t provide one up front, the AI will ask before creating any files.
Output language: All artifacts — proposal.md, design.md, tasks.md, and all AI questions and summaries — are written in the language of your request. If you write in English, the artifacts are in English; if you write in Chinese, the artifacts are in Chinese. When resuming an existing change, the dominant artifact language is preserved unless you explicitly ask to switch.