> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# open 阶段

> open 阶段调用 openspec-explore 和 openspec-new-change，把你的想法变成可执行的 OpenSpec change——一段引导式的需求澄清和文档创建过程。

open 阶段会把你的想法变成一个可执行的 change：探索需求、澄清范围、创建 proposal/design/tasks，并初始化 Comet 状态。从你的角度看，这是一段**引导式的对话**——Comet 会反复问你问题，确认理解对了，才动手写文档。

<Tip>
  正常情况下你只需要 <code>/comet</code>。 项目配置选择 Classic 后，<code>/comet</code> 会转发到{' '}
  <code>/comet-classic</code>
  ；自带意图识别，会读取文件状态，自动判断当前在 open 阶段并调用 <code>/comet-open</code>
  。本文描述的是内部阶段 Skill，只有想<strong>手动控制</strong>时才需要直接输入。详见
  <a href="#本阶段如何触发">本阶段如何触发</a>。
</Tip>

## 本阶段如何触发

`/comet-open` 通常**不是你手敲的命令**，而是 `/comet` 进入 Classic 后自动路由的结果。内部 `/comet-classic` 会读取 active change 列表与文件状态，整理路由上下文，再由运行时评分决定 route。

### 默认：用 /comet 自动识别

`/comet-classic` 每次调用都重新读取文件状态（不依赖对话历史），按以下条件路由到 open 阶段：

| 触发条件                                            | 行为                            |
| ----------------------------------------------- | ----------------------------- |
| route 为 `full` 且项目里没有活跃 change                  | 自动调用 `/comet-open`            |
| route 为 `full`，但已有 active change 且用户没有指定        | 暂停询问：继续已有 change 还是创建新 change |
| active change 的 `.comet.yaml` 缺失                | 自动调用 `/comet-open` 补齐状态       |
| 置信度不足、多个 active change 或 hotfix/tweak/full 信号冲突 | 暂停询问，不自动创建                    |

你只需要输入 `/comet` 并描述想做什么。配置选择 Classic 后，内部 `/comet-classic` 会判断是否需要新建 change，并在 open 完成后自动衔接 design。详见[自动推进机制](/zh/concepts/auto-transition)。

### 手动：什么时候才需要直接 /comet-open

* 关闭了自动衔接（`auto_transition: false`）——此时 `/comet-classic` 推进完一个阶段会停下，你需要手动调用下一个阶段 Skill。
* 只想单独跑 open 阶段（调试、或在阶段之间插入人工审核）。

**正常使用统一入口 `/comet`；只有手动控制阶段时才直接调用阶段命令。**

***

## 你会经历什么

open 阶段不是一次性生成文档，而是一段**多轮对话 + 多个停顿点**的流程。全程用你触发工作流时用的语言提问和产出文档。

```mermaid theme={null}
flowchart TD
    Start["你说出想法"] --> S1["加载 openspec-explore<br/>反复提问澄清"]
    S1 --> S1a{"大型 PRD /<br/>多个独立能力?"}
    S1a -->|是| Stop1["停顿点 1：PRD 拆分预检<br/>三选一"]
    S1a -->|否| S1sum["生成澄清摘要<br/>5 个必备部分"]
    Stop1 --> S1sum
    S1sum --> Stop2["停顿点 2：确认需求澄清完成"]
    Stop2 --> Stop3["停顿点 3：确认 change 名称"]
    Stop3 --> S2["加载 openspec-new-change<br/>逐个生成 proposal → design → tasks"]
    S2 --> S3["入口状态验证 + 内容完整性检查"]
    S3 --> Stop4["停顿点 4：审视三个文档并确认"]
    Stop5 --> Exit["comet-guard open --apply<br/>推进到下一阶段"]
```

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/piE9AoWsM20071ec/assets/open-phase-illustrations/01-idea-to-artifacts-funnel.png?fit=max&auto=format&n=piE9AoWsM20071ec&q=85&s=b658de6028423127a86b9f62787d952a" alt="小鱼把模糊想法经过澄清和确认整理成 proposal、design 和 tasks 三份文档" width="800" data-path="assets/open-phase-illustrations/01-idea-to-artifacts-funnel.png" />
</p>

<p align="center">open 阶段把模糊想法过滤成三份可执行的 OpenSpec 产物</p>

### 第一步：探索想法与澄清需求

Comet 加载 `openspec-explore`，**围绕你的想法持续提问**，直到能整理出一份完整的**澄清摘要**。它不会把一次问答当成"够了"——会一直问到这五个部分都清楚：

| 澄清摘要的五个必备部分 | 你要想清楚的事            |
| ----------- | ------------------ |
| **目标**      | 真正要解决的问题、期望的结果     |
| **非目标**     | 明确不做什么             |
| **范围边界**    | 涉及/不涉及的模块、用户、平台、数据 |
| **关键未知项**   | 假设、风险、依赖           |
| **验收场景草案**  | 核心成功场景 + 关键边界场景    |

### 停顿点 1：PRD 拆分预检（条件触发）

如果你的输入是一个**大型 PRD、路线图或完整产品计划**，或者澄清摘要里出现了**多个独立能力**，Comet 会在这里暂停，给你一份**候选拆分清单**（每个拆分项含建议名称、目标范围、非目标、依赖顺序、核心验收场景），然后让你三选一：

| 选项                        | 含义                                         |
| ------------------------- | ------------------------------------------ |
| **创建多个 OpenSpec changes** | 按拆分清单创建多个独立 change（每个都要用自己的 `/comet-open`） |
| **保持为一个 change**          | 不拆，继续单 change 流程，把不拆的原因记进文档                |
| **调整拆分方案后继续**             | 你描述调整，Comet 重新出清单再问一次                      |

<Tip>
  拆分后 Comet <strong>不会</strong>自动推进任何单个 change 到
  design。它会暂停问你想先做哪一个，只推进你选的那个，其余保持活跃，之后用 <code>/comet</code>{' '}
  恢复。
</Tip>

### 停顿点 2：确认需求澄清完成

在创建任何文档之前，Comet 把完整的澄清摘要（五个部分）摆给你看，**等你明确确认**。确认前不会创建 proposal/design/tasks，也不会用 `openspec-propose` 一次性生成。

### 停顿点 3：确认 change 名称

在 `openspec new change` 之前，Comet 让你定名字。**名字必须是 kebab-case 英文**（小写字母、数字、连字符，例如 `refine-requirements-doc`）。它会：

* 推荐 2-3 个 kebab-case 英文名，每个带一行范围说明
* 让你**自行输入名称**——如果你输入的是中文或非合规文本，它会转换成合规 kebab-case 并**回显让你确认**
* 如果名字和已有 change 冲突，报告冲突让你换一个

### 第二步：创建 change 结构

加载 `openspec-new-change`。完整工作流**默认不加载** `openspec-propose`（一次性生成全部），只有你明确要求时才允许。Comet 用**标准产物循环**逐个生成 proposal → design → tasks：

1. 刷新状态：`openspec status --change "<name>" --json`
2. 获取指令：`openspec instructions proposal|design|tasks --change "<name>" --json`
3. 读取 `dependencies`、遵循 `template` 和 `instruction`、应用 `context`/`rules` 约束（**不复制到文档内容里**）、写入 `resolvedOutputPath`
4. 每个 artifact 后再刷新状态确认

<Warning>
  如果 <code>openspec instructions</code> 失败、返回无效 JSON、或没提供可用的{' '}
  <code>resolvedOutputPath</code>，Comet 会<strong>立即停止</strong>并报告 OpenSpec 错误，
  <strong>不会</strong>回退成硬编码文档结构——那会绕过项目规则。change 名必须是你确认过的 kebab-case
  名，Comet 不会自作主张扩大或缩小范围。
</Warning>

### 第三步：入口状态验证 + 内容完整性检查

```bash theme={null}
node "$COMET_STATE" check <name> open
```

然后逐个确认三个文件存在且非空：proposal（背景/目标/范围）、design（架构决策/选型/数据流）、tasks（任务描述）。任何一个缺失或为空，Comet 都不会继续，而是回到创建步骤。

### 停顿点 4：审视三个文档并确认

Comet 把三个文档的摘要摆给你看（proposal 的背景目标范围、design 的架构决策选型、tasks 的任务数和关键任务），然后让你**二选一**：

| 选项            | 含义                       |
| ------------- | ------------------------ |
| **确认，继续下一阶段** | 文档符合预期，运行阶段 guard 推进     |
| **需要调整**      | 你给修改意见，Comet 改完相关文件再请求确认 |

### 退出：推进到下一阶段

```bash theme={null}
node "$COMET_GUARD" <change-name> open --apply
```

`--apply` 是必须的——没有它 `.comet.yaml` 会停在 `phase: open`，下一阶段的入口检查会失败。full workflow 推进到 `phase: design`；hotfix/tweak 直接跳到 `phase: build`（跳过 design）。

***

## 调用的 skill

| Skill                 | 用途           | 何时调用             |
| --------------------- | ------------ | ---------------- |
| `openspec-explore`    | 探索问题空间、澄清需求  | Step 1，立即执行，不可跳过 |
| `openspec-new-change` | 创建 change 骨架 | Step 2，立即执行，不可跳过 |

<Warning>
  完整工作流默认<strong>不加载</strong> <code>openspec-propose</code>（一次性生成全部
  artifacts）。只有用户明确要求时才允许。
</Warning>

## 产物

下图用 `<classic-root>` 表示当前 Classic OpenSpec 根目录：新项目默认是 `docs/openspec/`，保留旧布局的项目是 `openspec/`。实际位置由 `.comet/config.yaml` 中的 `classic.artifact_layout` 决定。

<Tree>
  <Tree.Folder name="<classic-root>/changes/<name>/" defaultOpen>
    <Tree.File name=".openspec.yaml" />

    <Tree.File name=".comet.yaml" />

    <Tree.File name="proposal.md" />

    <Tree.File name="design.md" />

    <Tree.File name="tasks.md" />

    <Tree.Folder name="specs/<capability>/">
      <Tree.File name="spec.md" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

初始化 Comet 状态：

```bash theme={null}
node "$COMET_STATE" init <name> full
```

## 幂等性：可以安全重复

open 阶段所有操作都可以安全重复执行。如果 `.comet.yaml` 已经在 `phase: open` 且三个产物都已存在，Comet 会**跳过已完成步骤**，从第一个缺失的步骤继续。这让你在中断后重新调用 `/comet` 也不会搞乱状态。

## 四个停顿点一览

open 阶段有 4 个停顿点（全局编号 1-4，整个五阶段工作流共 13 个，见[五阶段停顿点和用户选择点](/zh/concepts/decision-points)）：

| 停顿点         | 何时出现             | 你要做什么          |
| ----------- | ---------------- | -------------- |
| 1 PRD 拆分    | 输入是大 PRD 或多个独立能力 | 拆分 / 不拆 / 调整方案 |
| 2 需求澄清完成    | 澄清摘要生成后          | 确认理解对了         |
| 3 change 名称 | 创建 change 前      | 选名 / 自定义名      |
| 4 文档审视      | 三文档生成后           | 确认 / 要调整       |

所有停顿点都遵循[决策点协议](/zh/concepts/decision-points)——Comet 不能用推荐规则、默认值或"用户应该会同意"来代替你的明确选择。

## 常见问题

<AccordionGroup>
  <Accordion title=".comet.yaml 缺失怎么办">
    不要用 `/opsx:new` 绕过——它只创建 OpenSpec artifacts，不会创建 `.comet.yaml`，change 会落在 Comet 状态机之外。重新运行 `/comet`；配置进入 Classic 后会通过 `/comet-open` 补齐状态。
  </Accordion>

  <Accordion title="change 名称有什么限制">
    必须是 kebab-case 英文（小写字母、数字、连字符）。中文或非合规名称会被转换成 kebab-case
    并回显让你确认。和已有 change 冲突会报告让你换一个。
  </Accordion>

  <Accordion title="openspec instructions 失败了怎么办">
    Comet 会立即停止 artifact 创建并报告 OpenSpec 错误，不会回退为硬编码文档结构。检查 OpenSpec CLI
    是否正常、`template`/`instruction`/`dependencies` 是否满足。
  </Accordion>

  <Accordion title="大型 PRD 一定要拆吗">
    不一定。拆分预检会给你三选一（拆分 / 保持一个 / 调整方案），你可以选择保持为一个 change，但要把不拆的原因记进文档。
  </Accordion>
</AccordionGroup>

## 下一步

* [design 阶段](/zh/phases/design) — open 完成后进入深度设计
* [五阶段停顿点和用户选择点](/zh/concepts/decision-points) — open 的 4 个停顿点详解
* [大型 PRD 拆分](/zh/guides/prd-splitting) — Step 1a 的完整机制
* [自动推进机制](/zh/concepts/auto-transition) — open 完成后如何自动衔接 design