> ## 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. # 工作流概念 > 理解 /comet 如何按项目配置进入经典 Spec 模式，以及 Classic 如何把 OpenSpec 和 Superpowers 串成五阶段。 用户正常只需要调用 `/comet`。它读取 `.comet/config.yaml`，按项目配置确定性地进入 Native 或 Classic；配置选择 Classic 时，内部转发到永久入口 `/comet-classic`，再由 Classic 把一次变更拆成 open、design、build、verify、archive 五个阶段。两套工作流的 change、状态和产物彼此独立。 Classic 把 OpenSpec 和 Superpowers 连成一条可恢复的工作流。`/comet-classic` 自带意图识别，会读取活跃 change、`.comet.yaml` 和实际文件状态，判断应该新建、恢复、进入轻量预设，还是调用当前阶段 Skill。用户无需先判断自己是否处于 open、design、build、verify 或 archive。 下文用 `` 表示当前 Classic OpenSpec 根目录：新项目默认是 `docs/openspec/`，保留旧布局的项目是 `openspec/`。实际位置由 `classic.artifact_layout` 决定，详见[项目文件结构](/zh/guides/project-structure)。 **Classic 主要适配 Fable 5、GPT-5.6 以下的模型能力档。对这类模型，明确的 Spec、设计、计划、TDD、调试和审查阶段能够减少遗漏与流程漂移**；Comet 的现有真实基线评估已验证，这种约束在较低能力档模型上能保持良好的任务覆盖和完成效果。Fable 5、GPT-5.6 及同档强模型通常更适合使用执行方法更轻的 [Native 工作流](/zh/concepts/native-workflow)。 ## 哪些值得注意 | 什么是需要关心的 | 结论 | | ------------ | -------------------------------------------------- | | 用户入口 | 使用 `/comet`；项目配置决定进入 Classic 还是 Native | | Classic 内部入口 | `/comet-classic`，负责意图识别、文件状态读取和阶段路由 | | 适用模型 | Fable 5、GPT-5.6 以下、需要更细步骤与过程约束的模型 | | 流程 | `open` → `design` → `build` → `verify` → `archive` | | 你什么时候参与 | 需求、设计、执行模式、验证失败、归档前确认 | | 恢复靠什么 | OpenSpec 产物、`.comet.yaml` 和运行证据 | | 哪些是高级细节 | handoff hash、归档目录、路由判断，排障时再读 | ## 为什么把 OpenSpec 和 Superpowers 连接起来 OpenSpec 和 Superpowers 各有所长，但单独使用时都有短板： | 工具 | 擅长 | 短板 | | ----------- | ------------------------------------ | ----------------------------------------- | | OpenSpec | WHAT — 需求、提案、spec 生命周期、delta spec、归档 | 提案和 tasks 缺少深度设计的细节 | | Superpowers | HOW — brainstorming、技术设计、计划、执行、收尾、验证 | 缺少状态化设计，spec 完成后只有勾选，Agent 恢复时容易反复回看文档和代码 | ```mermaid theme={null} flowchart LR A["用户目标"] --> B["OpenSpec: WHAT"] A --> C["Superpowers: HOW"] B --> D["proposal/design/tasks/spec delta"] C --> E["Design Doc/Plan/实现/Review"] D --> F["验证通过"] E --> F F --> G["归档到主 specs"] ```

小鱼把 OpenSpec 的 WHAT 和 Superpowers 的 HOW 连接到 Comet 工作流

OpenSpec 记录 WHAT，Superpowers 组织 HOW，Comet 把两者夹到同一条可恢复链路上

Comet 的职责不是替代任何一方，而是： * **把两者的产物对齐到同一条链**——OpenSpec 记录的 WHAT 和 Superpowers 组织的 HOW 指向同一个 change。 * **用状态机和守卫保证交接可靠**——不让 Agent 靠对话历史猜进度，而是从文件状态和可检查证据恢复。 * **把文档同步自动化**——handoff、状态更新、验证和归档都进脚本流程，减少"记得更新设计文档""记得同步 spec""记得归档"这类反复提醒。 ## 五个阶段 | 阶段 | 负责方 | 目标 | 主要产物 | | ------- | ----------- | ------------------------------------ | -------------------------------------------------------------------------------------- | | open | OpenSpec | 把想法变成 OpenSpec change | `proposal.md`、`design.md`、`tasks.md`、delta spec | | design | Superpowers | 做深度技术设计 | `docs/superpowers/specs/...-design.md`、handoff 包 | | build | Superpowers | 写计划并执行 | `docs/superpowers/plans/...md`、代码改动、测试证据 | | verify | 双方 | 验证实现符合设计和 spec | 验证报告；`branch_status` 保持 `pending` | | archive | OpenSpec | 合并 delta spec 并归档，给 Superpowers 文档打标 | `/changes/archive/YYYY-MM-DD-name/`、design doc/plan 的 `archived-with` 标注 | ### open — OpenSpec 记录 WHAT `/comet-open` 创建一个 OpenSpec change，产出： Comet 会用 OpenSpec 的 `openspec instructions` 流程逐个生成 proposal、design、tasks，遵守项目的 `template`、`instruction`、`dependencies` 和 `resolvedOutputPath`，而不是一次性批量生成。完整工作流禁止跳过 brainstorming 直接 one-shot 生成提案。 必须用 `/comet-open` 而不是 `/opsx:new` 创建 change。`/opsx:new` 只创建 OpenSpec artifacts，不会创建 `.comet.yaml`，change 会落在 Comet 状态机之外。 ### design — Superpowers 深度设计，OpenSpec 保持权威 这是两套工具物理对接的阶段。Comet 用 `comet-handoff.mjs` 生成一个交接包，把 open 阶段的 OpenSpec artifacts（`proposal.md` 的需求动机、`design.md` 的高层方案、`tasks.md` 的任务边界，以及 `specs//spec.md` 里的 delta spec）整理成 Superpowers 能读懂的上下文，再交给 Superpowers `brainstorming` 做深度设计。 ```mermaid theme={null} flowchart LR A["OpenSpec 产物"] --> B["comet-handoff.mjs --write"] B --> C["design-context.json/md"] C --> D["Superpowers brainstorming"] D --> E["Design Doc"] B --> F["handoff_hash 写入 .comet.yaml"] ``` Design Doc 的 frontmatter 显式声明 OpenSpec 是权威来源： ```yaml theme={null} --- comet_change: role: technical-design canonical_spec: openspec # OpenSpec 是权威，不是 Design Doc --- ``` 关键约束：**Agent 不能写第二份需求 spec**。如果 delta spec 缺少验收场景，只能在 `specs/*/spec.md` 上写 Spec Patch（回写），不能扩大范围。 Spec Patch 是 design 阶段把需求缺口写回 OpenSpec 的唯一合法通道，它有三个硬边界： * **只能做加法或修正**——补充验收场景、修正模糊描述、补充边界条件；不能重写 delta spec 的结构或范围。 * **只回写 OpenSpec**——Spec Patch 写回 `specs/*/spec.md`，不进 Design Doc。Design Doc 只记 HOW，OpenSpec 始终是 WHAT 的唯一权威。 * **写完必须重新生成 handoff**——delta spec 内容变了，hash 必然漂移，离开 design 阶段时 guard 会 FATAL。 如果改动超出了 Spec Patch 的边界（接口变化、新组件、数据流变化、全新 capability），属于设计层面的重大变更：要么在当前 change 退回 brainstorming 重新对齐，要么开新 change。这类"中途改 spec"的实践场景和具体操作见[中途修改 spec 或回退工作流](/zh/guides/mid-workflow-changes)。 ### build — Superpowers 执行，以 OpenSpec 任务边界为输入 计划由加载 Superpowers `writing-plans` 的子代理生成，它的 frontmatter 是两个世界的显式链接： ```yaml theme={null} --- change: design-doc: docs/superpowers/specs/YYYY-MM-DD--design.md base-ref: <实现前的 git HEAD> --- ``` 计划输入是 Design Doc（Superpowers）+ `tasks.md`（OpenSpec 任务边界）。Design Doc 已经在 design 阶段消化了 proposal、原始 design 和 delta spec，所以 build 阶段不必回读这些原始 artifacts；`tasks.md` 则作为活文档持续核对任务边界。执行方式由用户选择：`subagent-driven-development` 或 `executing-plans`，配合 `isolation`（branch/worktree）、`tdd_mode`、`review_mode`。 ### verify — 双方都查，用 hash 检测漂移 verify 会加载 Superpowers `verification-before-completion`，然后按 `verify_mode` 分支： * **light**（6 项检查）：任务完成、diff 对比、构建、测试、安全、轻量代码评审。跳过 spec 覆盖、Design Doc 一致性和漂移检查。 * **full**：额外加载 `openspec-verify-change`，同时检查 OpenSpec `design.md` 和 Superpowers Design Doc，包括"delta spec 与 design doc 无矛盾"。 ## 产物如何交接：handoff hash Comet 用一个 **handoff hash** 把 OpenSpec artifacts 和后续阶段绑在一起，这是它可靠性的核心机制。 ### hash 怎么算 `comet-handoff.mjs` 对这些文件计算内容 hash： ```text theme={null} /changes//proposal.md /changes//design.md /changes//tasks.md /changes//specs//spec.md # 每个 delta spec ``` 对每个文件先算 per-file sha256，再把"相对路径 + per-file sha256"拼起来算最终 sha256，得到 `handoff_hash`。路径统一用正斜杠，保证 macOS/Linux/Windows 的 hash 输入字节一致。 ### hash 在各阶段的作用 ```mermaid theme={null} flowchart TD A["design 阶段"] --> B["comet-handoff --write 生成 hash"] B --> C["handoff_hash 写入 .comet.yaml"] C --> D["guard 在离开 design 时重算 hash"] D --> E{"hash 一致?"} E -->|否| F["FATAL: artifacts 漂移，重新生成 handoff"] E -->|是| G["进入 build"] G --> H["verify 阶段"] H --> I["--hash-only 重算 hash"] I --> J{"hash 一致?"} J -->|是| K["OpenSpec artifacts 未变，可省略全文重读"] J -->|否| L["全文重读所有 artifacts"] ``` | 阶段 | hash 的作用 | | ---------------- | --------------------------------------------------------------------- | | design | 生成 hash，写入 `.comet.yaml` 的 `handoff_hash` 和 `handoff_context` | | guard（离开 design） | 重算 hash，如果和记录的不一致就 FATAL，提示重新生成 handoff | | verify | 用 `--hash-only` 快速重算，hash 一致说明 OpenSpec artifacts 没变，可省略全文重读；不一致则全文重读 |

小鱼用 hash 夹子把 OpenSpec 产物和后续阶段证据连接起来

handoff hash 像一枚可靠的夹子，把前后阶段的证据绑在一起

### handoff 包格式 `comet-handoff.mjs ... --write` 在 `/changes//.comet/handoff/` 下产出： | 模式 | 产出文件 | 内容 | | ---------- | ------------------------------------------- | ----------------------------------------------------------- | | `off`（默认） | `design-context.json` + `design-context.md` | 完整 artifacts 内容，每文件带 SHA256 | | `beta`（压缩） | `spec-context.json` + `spec-context.md` | spec 文件 verbatim 投影 + supporting 文件只存 hash，节省约 25–30% token | JSON 包含 `change`、`phase`、`mode`、`canonical_spec: openspec`、`context_hash` 和 `files` 数组。guard 会额外验证 markdown 包带有 `Generated-by:` 标记和每个文件的 `Source:`/`SHA256:` 引用，保证 Superpowers 消费的上下文可追溯。 beta 压缩模式是 Comet 的上下文压缩 beta 功能在 handoff 环节的体现——两种模式的原理、token 节省测算和何时该开 beta，见[上下文压缩机制](/zh/concepts/context-compression)。 ## 如何处理 spec 范围 Comet **不做 spec 去重或重叠检测**。它处理 spec 范围问题的方式是 delta spec 生命周期 + 归档时委托 OpenSpec 合并。 大型 PRD 拆分是 Comet 贴近现实需求开发的独立特性——把一个大需求拆成多个可独立设计、交付、归档的 change。详见[大型 PRD 拆分](/zh/guides/prd-splitting)。 ### delta spec 语义 delta spec 的 `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` 是 **OpenSpec 原生概念**，不是 Comet 发明的。Comet 消费但不重写这些语义： * open 阶段创建 delta spec，描述本次变更对哪些能力的增删改。 * build 阶段把 delta spec 当作**活文档**——小修直接改，中改重新 brainstorming，大改通过 `/comet-open` 开新 change。 * archive 阶段由 OpenSpec CLI 按 `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` 语义合并 delta 到主 spec。 ### verify 的 spec 漂移决策 build 阶段允许小改 delta spec（补充验收场景、边界条件等），这些改动不一定同步回 Design Doc。verify 阶段会把 delta spec 和 Design Doc 放在一起查——如果发现 delta spec 里有内容、Design Doc 没反映（即 spec 漂移），**这是一个需要你做决策的阻塞点**，Comet 不会自动选，会暂停等你三选一： | 选项 | 适用场景 | 做什么 | 之后 | | -- | ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------- | | A | 偏差合理但 Design Doc 漏了，想留个说明 | 在 Design Doc 追加 "Implementation Divergence" 段，记录偏差原因 | 继续验证，不再触发改动归因 | | B | 偏差较大，设计没跟上 | `verify-fail` 回 build，加载 `brainstorming` 重新对齐 Design Doc 和 delta spec | 修完重新走 build→verify | | C | 偏差可接受，不想补 Design Doc | 确认接受，继续验证 | 归档时 Design Doc 自动标记 `superseded-by-main-spec`，让位给主 spec | 判断口径：偏差是**说明性问题**（Design Doc 漏记，但实现没问题）选 A；是**设计性问题**（Design Doc 跟不上现实）选 B；偏差无关紧要、不值得回头补，选 C。 ## 如何归档 archive 阶段关闭整个 spec 生命周期。`comet-archive.mjs` 是归档的确定性入口，但它把 delta→主 spec 的合并**委托给 OpenSpec CLI**，自己做前后校验。 ### 归档流程 ```mermaid theme={null} flowchart TD A["最终确认决策点"] -->|确认归档| B["comet-archive.mjs"] A -->|需要调整| C["archive-reopen 回 verify"] B --> D["校验入口状态: phase=archive, verify_result=pass"] D --> E["检查归档目标不冲突"] E --> F["写 pending action checkpoint"] F --> G["openspec archive --yes 合并 delta 到主 spec"] G --> H["校验主 spec 无 delta 标题残留"] H --> I["标注 design doc 和 plan 的 archived-with"] I --> J["设置 archived: true, 移动目录"] ``` `comet-archive.mjs` 逐步做： 1. **校验 change 名**（kebab-case）。 2. **定位 change 目录**，如果已被之前的归档移走，扫描 archive 目录恢复。 3. **校验入口状态**：`phase` 必须是 `archive`，`verify_result` 必须是 `pass`。 4. **检查归档目标可用**：`/changes/archive/YYYY-MM-DD-` 不能已存在。 5. **写 pending action checkpoint**，支持归档中断后恢复。 6. **调用 OpenSpec archive**：`openspec archive --yes`，这一步真正执行 delta→主 spec 合并并移动 change 目录。 7. **解析归档目录**：重新定位 OpenSpec 实际放的位置（日期前缀可能变化）。 8. **校验主 spec 干净**：扫描 `/specs/*/spec.md`，如果残留 `## ADDED/MODIFIED/REMOVED/RENAMED Requirements` 这类 delta-only 标题就 FATAL。 9. **标注 Superpowers 文档 frontmatter**：在 design doc 和 plan 的 frontmatter 写入 `archived-with: `，把 Superpowers 产物锚定到具体的归档目录；design doc 额外加 `status: final`，表明设计文档生命周期结束。幂等设计，已有标注会先移除 `archived-with:` 旧值再重写。这样 Agent 在归档后检索 Design Doc/Plan 时，能直接从 frontmatter 知道它属于哪次归档、是否已结案，而不必反查 `.comet.yaml`。 10. **更新归档状态**：设置 `archived: true`，Run 状态转为 `completed`，清除 pending action。 ### 归档目录结构 ```text theme={null} /changes/archive/YYYY-MM-DD-/ ``` 日期取 UTC（`new Date().toISOString().slice(0,10)`），保证跨时区一致。 归档成功后不要再跑 `comet-guard archive`——活跃目录已不存在，guard 会报错。归档完整性由退出码和归档目录状态判断。 ### 预览 `comet-archive.mjs ... --dry-run` 可以预览归档流程而不真正执行 OpenSpec，用 `[DRY-RUN]` 标记标注，报告多少步会成功。 ## Classic 如何判断当前入口 每次用户调用 `/comet` 并由项目配置进入 Classic 后，`/comet-classic` 都会重新读取活跃 change 和 `.comet.yaml`，而不是依赖聊天历史。入口判断不再只靠提示词里的经验规则；Comet 会把用户原话、active change 列表和风险信号整理成结构化路由上下文（实现类型名为 `CometIntentFrame`），再交给运行时评分得到最终 route。 从用户视角，你只需要知道这些结果： | route | 什么时候出现 | 下一步 | | -------------- | ------------------------------------------ | -------------------------------- | | `full` | 新能力、public API、schema、跨模块或架构变更 | 进入 `/comet-open` | | `hotfix` | 修已有异常、回归或错误行为，且没有新增能力/API/schema/跨模块风险 | 进入 `/comet-hotfix` | | `tweak` | 文案、配置、文档、prompt 或单一 OpenSpec change 的轻中量修改 | 进入 `/comet-tweak` | | `resume` | 用户明确继续某个 active change | 读取该 change 的 `.comet.yaml` 并恢复阶段 | | `ask_user` | 置信度不足、多个 active change、证据缺失或用户显式路径与风险信号冲突 | 暂停让你选择 | | `out_of_scope` | 你只是提问，没有要求启动或恢复工作流 | 不初始化 change | ```mermaid theme={null} flowchart TD A["用户调用 /comet"] --> B["配置路由到 /comet-classic"] B --> C["openspec list --json"] C --> D["整理路由上下文"] D --> E["运行时评分 route"] E --> F{"route?"} F -->|full| G["/comet-open"] F -->|hotfix| H["/comet-hotfix"] F -->|tweak| I["/comet-tweak"] F -->|resume| J["读取 .comet.yaml 并恢复"] F -->|ask_user| K["停顿点：让用户选择"] ``` 路由上下文让路由可解释：如果 Comet 没有足够证据证明某条路径安全，它会问你，而不是把 `hotfix`、`tweak` 或 `full` 猜到底。 ## 用户会在哪些地方参与 Comet 会自动推进无歧义阶段，但不会替你做产品或风险决策。常见阻塞点包括： * open 阶段确认 proposal、design 和 tasks（大型需求还会遇到 PRD 拆分，见[大型 PRD 拆分](/zh/guides/prd-splitting)）。 * design 阶段确认方案，以及是否写 Spec Patch。 * build 阶段选择隔离方式和执行方式。 * verify 失败后选择修复或接受偏差（A/B/C）。 * archive 前做最终确认。 * hotfix/tweak 命中升级信号时选择继续轻量路径或升级 full。 ## 轻量预设 `/comet-hotfix` 和 `/comet-tweak` 都跳过完整 brainstorming，但仍保留 OpenSpec 状态、验证和归档。两者的定位不同： * **`/comet-hotfix`** 适合快速 bug 修复，无需 Design Doc。 * **`/comet-tweak`** 适合 OpenSpec 链式的轻量变更——配置调整、文档或提示词优化，以及 **spec 驱动（含 delta spec）的中等变更**。在 tweak 里 delta spec 是一等产物，单凭"需要 delta spec"不构成升级理由。 共同前提：变更能装进单个 OpenSpec change，不需要 Superpowers 深度设计。一旦出现跨模块/跨层协调、新 public API、schema 变更或深层架构问题等质变信号，应升级到 full（升级路径见[中途修改 spec 或回退工作流](/zh/guides/mid-workflow-changes)）。 ## 下一步 * [大型 PRD 拆分](/zh/guides/prd-splitting) — 把大需求拆成多个可独立交付的 change * [状态与配置](/zh/concepts/state-management) — 理解 `.comet.yaml` 字段和状态守卫 * [Skill 的类型与用途](/zh/concepts/skills) — Comet Skill 的三类来源 * [comet-handoff](/zh/scripts/comet-handoff) — 交接包和 hash 的脚本细节 * [comet-archive](/zh/scripts/comet-archive) — 归档脚本的完整说明