comet-open

Files (3)

• SKILL.md
• openai.yaml · agents/
• batch-changes.md · reference/

SKILL.md (first lines)

# Comet Phase 1: Open

On first entering a phase, handing off to a new Agent, or restoring context, read and follow [Task Context and Artifact Language](../comet-classic/reference/scripts.md#task-context-and-artifact-language). Prefer the current continuation or claimed Action's `contextRequest`; do not retrieve repeatedly during uninterrupted work in the same phase.

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 a change is initialized, read `classic.language` from project `.comet/config.yaml`, then global `~/.comet/config.yaml`. After initialization, reuse `configuration.language` from the current valid response; use `comet state get <name> language` only when it is missing. 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 the response already includes `agent.continuation.mode`, follow `comet-classic/reference/auto-transition.md` first. `wait` distinguishes manual handoff from waiting for the original executor under auto-transition.md, without running recovery queries merely because the compatibility field says `nextAction.kind: reconcile`. Use the current response’s commands and inputs; submit `completion` only after the Skill’s actual work is complete. Recovery rules below based on `nextAction.kind` apply only to older responses without `mode`.

When resuming an existing change, reuse the latest valid continuation and ownership for the same workspace and Run. Query `comet state next <name> --json` only on cold recovery, external changes, or missing information:

- `sdk`: reuse the Run and recover according to `data.nextAction.kind`. Investigate a claimed Action with an unknown outcome before recreating or redispatching work.
- `compat`: reuse the original flow and `.comet.yaml`; never migrate it automatically.
- If the command fails, inspect its error, ownership record, Run, and actual state file. Stop on conflict or malformed state. If local Run history is missing, first check `run_checkpoint` in the state file and follow `/comet-classic`'s recovery steps to resume the saved phase. Only an older state without a checkpoint may return to Open after the user explicitly consents to restoration and fresh evidence and approvals. Prepare and initialize a workspace only when no Runtime owns a valid change directory. A missing filename alone is not evidence that initialization is needed.

For SDK and Compat, resolve and bind the workspace on cold recovery, changed workspace, or missing bindings. Reuse an existing valid selection and projectRoot:

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

For a new change, initialize the SDK Run immediately after creating the basic OpenSpec directory, then select it. Never write a selection before initialization.

### 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 the SDK Run; 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`:

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

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

When the user provides a large PRD, roadmap, complete product proposal, or multiple independently deliverable goals, read and follow [PRD splitting and batch recovery](reference/batch-changes.md) before creating artifacts. Also read it when resuming a batch recorded in `.comet/batches/<batch-id>.json`. Continue directly for a single change; reuse the approved scope for a confirmed split item.

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

### 2. Create the change structure and initialize state

Follow the shared [creation and recovery order](../comet-classic/reference/sdk-methods.md#entry-and-artifacts): create the OpenSpec base directory before SDK initialization; resume an existing Run instead of creating it again.

**Required now:** Load the `openspec-new-change` skill using the Skill tool. Do not skip this step.

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

**Adapt external OpenSpec instructions:** Use its change-creation method only. Do not directly invoke the official CLI, adopt a fixed cwd, or write to a fixed OpenSpec root. Route creation, status, and instructions through `comet classic openspec -- <args...>`. Use this invocation's logical roots, including `<classic-change-dir>`, for all paths.

Do not load `openspec-propose` by default in the full `/comet-classic` flow. Load it only if the user explicitly requests a proposal and artifacts generated together.

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

From rpamis/comet, MIT.

More from rpamis/comet