Comet Open

Comet Phase 1: Open

Before starting or resuming, read and follow comet-classic/reference/classic-layout.md. All OpenSpec CLI calls in this file must use the adapter, and all paths must use the <classic-*> logical roots bound by that protocol.

Prerequisites

• There is no active change, or the user wants to create a new one.

Steps

0. Set the output language

Every question and artifact-generation request passed to OpenSpec must specify the resolved Comet artifact language using a normalized ID such as en or zh-CN. Before .comet.yaml exists, read classic.language from project .comet/config.yaml, then global ~/.comet/config.yaml. After initialization, use comet state get <name> language. Fall back to the current request's language only when no language is configured. proposal.md, design.md, and tasks.md must primarily use that language.

0a. Bind the current change

When resuming an existing change, first inspect <classic-change-dir>/.comet.yaml:

• If it exists and parses, run comet classic workspace resolve <change-name> --json, enter the returned projectRoot, and select the change there.
• If state is missing but the change directory is valid, prepare the workspace using the selected isolation mode. Enter the returned projectRoot, run comet state init <change-name> full --isolation <selected-isolation>, and then select the change.
• If state is malformed, stop and report the parse error. Resume only after manual repair using version control, a backup, or verifiable artifacts. Do not overwrite damaged state with state set.

comet classic workspace resolve <change-name> --json
# Enter the returned projectRoot
comet state select <change-name>

For a new change, initialize .comet.yaml first and immediately run the select command above. Do not manually write a selection before state exists.

0b. Choose and prepare the workspace before Open

Read comet-classic/reference/workspace.md when creating a Classic change. Choose the workspace before creating OpenSpec artifacts or .comet.yaml; do not defer this to Build.

• If the user explicitly requests parallel work, use worktree directly. Prepare the independent workspace before creating OpenSpec artifacts or state.
• If isolation is unspecified, follow the reference. When a choice is needed, present the available current, branch, and worktree options; a recommendation does not replace the user's choice.
• current and branch still require serial work. Do not describe them as suitable for concurrent sessions.

Prepare the workspace before running OpenSpec new:

comet classic workspace prepare <name> --isolation <current|branch|worktree> --json
# Enter projectRoot; run subsequent OpenSpec/state commands and artifact writes there

The prepare command reuses a registered worktree with the matching branch. If the branch remains but the registered worktree was removed, it recreates the worktree. Request an explicit rebind only if the branch was renamed, taken over for other work, or its ownership cannot be established.

0c. Check OpenSpec compatibility

Run this once on first use or after the upstream installation changes, and record the version for troubleshooting:

comet classic openspec -- --version

Check actual capabilities rather than inferring compatibility from the version. Status must provide changeRoot, applyRequires, and each artifact's requires, outputPath, and status. Instructions must provide a usable resolvedOutputPath. The adapter has been checked against the state interfaces in OpenSpec 1.11.0/1.12.0; compatibility with every historical version is not guaranteed. If a command is unavailable, exits nonzero, or lacks a required capability, stop with the error and upgrade guidance. Do not upgrade the user's environment automatically.

After creation, comet state artifacts <name> --json checks paths, all required dependencies, and actual files. It recursively expands applyRequires together with Classic's mandatory proposal/tasks into the full dependency closure. If that closure requires design, do not skip it because instructions call it optional; design outside the closure is not mandatory.

Skipping specs is valid only when the request changes no behavioral specification, .openspec.yaml explicitly sets skip_specs: true, and no conflicting spec files exist. Supported roles are proposal/specs/design/tasks. Report unsupported mandatory roles or output patterns instead of guessing how to handle them.

1. Explore the idea and clarify requirements

Required now: Load the openspec-explore skill using the Skill tool. Do not skip this step.

<!-- external-openspec-skill-override -->

Adapt external OpenSpec instructions: Use its exploration method only. Do not follow instructions that directly invoke the official CLI, change to a fixed cwd, or read/write hard-coded OpenSpec directories. Use comet classic openspec -- <args...> for every CLI call and this invocation's bound <classic-*> roots for every path.

Reuse the user's PRD, designs, and confirmed facts first. Identify gaps in the following areas and produce a clarification summary. Ask only about unknowns that would change scope, the solution, or acceptance. If information is sufficient, proceed without additional questions; there is no minimum number of clarification rounds.

• Goal: the user's actual problem and desired result.
• Non-goals: what this change explicitly excludes.
• Scope: included and excluded modules, users, platforms, or data.
• Key unknowns: unresolved assumptions, risks, or dependencies.
• Draft acceptance scenarios: at least the core success path and important edge cases.

The summary must include all five areas: goal, non-goals, scope, key unknowns, and draft acceptance scenarios.

Before asking the user, read comet-classic/reference/decision-point.md. State the question, recommendation and reasoning, and each option's impact; prefer an available AskUserQuestion tool. Ask only about current gaps. If missing facts or materials cannot support real options, explain what is missing and request it. Apply this protocol to questions from the external exploration skill as well; loading that skill does not permit omitting choices or deciding for the user.

Reference a full PRD by path and relevant sections rather than copying it. Do not reconfirm settled facts; clarify only actual contradictions. OpenSpec skills remain mandatory dependencies. Return to Comet when exploration ends; external skills must not independently enter design, implementation, or archive. Exploration approval does not replace Open's final artifact confirmation.

1a. Confirm whether to split the PRD before creation

For a large PRD, roadmap, complete product proposal, or a clarification summary containing multiple independent features, modules, user journeys, or milestones, assess whether multiple changes are needed before creating OpenSpec artifacts.

Use the clarified information to present a proposed split. Each item must include:

• Suggested change name.
• Goal and scope.
• Explicit non-goals.
• Dependencies or recommended execution order.
• Core acceptance scenarios.

Recommend splitting when any of these apply:

• The PRD contains multiple features that can be designed, built, verified, and archived independently.
• It spans multiple modules or user journeys, with a portion that can ship independently.
• It has distinct delivery milestones.
• Several delta specs serve independent goals that can be accepted and shipped separately. Document or task counts alone do not determine a split.
• Failure or delay in one part should not prevent the others from proceeding.

If you recommend splitting, pause under comet-classic/reference/decision-point.md and wait for the user's choice. Include all these options:

• “Create multiple OpenSpec changes”: create each proposed item as an independent change.
• “Keep one change”: continue with one change and record the reason in proposal/design/tasks.
• “Revise the split”: ask for the desired adjustments, revise the list, and obtain confirmation again.

Create every accepted item through /comet-open, not directly through /opsx:new. /comet-open creates both OpenSpec artifacts and .comet.yaml, keeping each change under the Comet state machine.

Do not create proposal.md, design.md, or tasks.md before the user chooses how to split the PRD. If they choose multiple changes, this /comet-open invocation handles split confirmation and scheduling only, then invokes /comet-open for each item in the approved order.

Immediately save the confirmed batch to .comet/batches/<batch-id>.json. Use a stable kebab-case batch-id. Record at least version, the original goal summary, creation time, ordered change names, and each item's goal, scope, non-goals, acceptance scenarios, and pending|open-complete|selected status. Atomically update the file after each item is created or completed. This list tracks batch order and progress; it does not replace each change's .comet.yaml.

When invoking /comet-open for a batch item, label it “confirmed split item” and pass its goal, scope, non-goals, and acceptance scenarios. Skip the PRD split assessment for a confirmed item unless that item still clearly contains multiple independent features.

Do not automatically move an individual batch item from Open to /comet-design. When the batch is complete, pause and ask which change to start. Advance only the selected change to /comet-design; leave the others unarchived for later recovery through /comet-classic.

Check every completed batch item; do not skip this: After all items finish Open, run the following for every <name> on the confirmed list:

comet state check <name> design --json

This entry validates the full required closure, actual OpenSpec outputs, and Comet state. Do not repeat a separate status scan. isComplete is diagnostic; optional artifacts do not block progress. Query status only after a failed check to locate missing dependencies or diagnose reported path/capability errors.

If any split item fails these checks, do not announce batch completion or ask which change to start. Stop further advancement and resume /comet-open at that change's first ready or blocked artifact. If OpenSpec checks pass but Comet state checks fail, repair .comet.yaml initialization or phase first, then rerun the batch checks.

Only after every item passes entry checks may you ask which change to start. Mark the user's chosen item selected in the batch list and advance that change alone to /comet-design. Leave the others unarchived for later recovery through /comet-classic.

On recovery, read .comet/batches/<batch-id>.json, then run the checks above for its created, unarchived changes. Do not recreate items that already pass. Resume failed items from the first ready artifact returned by OpenSpec. Create the remaining items from the saved list. If the list is missing or damaged, stop and ask the user to rebuild or confirm it; do not infer the original batch from directory names.

1b. Summarize requirements and choose the change name

Before creating artifacts, turn Step 1's findings into a resolved brief containing goal, non-goals, scope, key unknowns, and draft acceptance scenarios. Derive an English kebab-case change name that accurately describes that scope.

• Continue directly when scope and name are clear. Do not add a pause solely to approve the summary or name; final review confirms the name, scope, and artifact content together.
• If the user supplied a name, normalize it to kebab-case and echo it in a progress update. No reconfirmation is needed when normalization preserves meaning.
• Reuse a confirmed batch item's summary and name. Clarify again only if scope has changed or the list lacks needed information.
• Ask a joint question under comet-classic/reference/decision-point.md only when mutually exclusive scope or target-change choices remain. Naming preference alone is not a reason to pause.

OpenSpec change names must use English kebab-case: lowercase letters, digits, and single hyphens. If a name conflicts but the goal is clear, choose a nonconflicting name with the same meaning and continue. Ask the user only when you cannot determine whether to reuse an existing change or create a new one.

While the resolved brief or change identity is still unclear, do not run comet classic openspec -- new change or create proposal/design/tasks. Resolve the missing information or genuine user decision before Step 2.