comet-classic

Comet Classic — OpenSpec + Superpowers

Classic 分为五个阶段：Open → Design → Build → Verify → Archive。OpenSpec 管理规范和归档。Superpowers 提供设计方法，以及用户选定的规划、执行和审查方法。完整工作流需要进行头脑风暴并确认设计；热修复/微调则遵循预设步骤。

1. 解析目标和工作区

在新任务开始或主机发生变化时，先阅读并执行主机能力检查，然后再批准 Open。执行配置变更时，只检查新策略所需的能力。

开始或恢复工作前，使用 comet-classic/reference/classic-layout.md 解析工件路径，并遵循 comet-classic/reference/scripts.md 中的“CLI 引导”。使用公开的 Comet CLI 及其 OpenSpec 适配器。只阅读当前操作所需的章节；上下文中已有的有效说明可重复使用。

• 未明确调用 Classic，且可能需要恢复现有工作时：阅读 comet-classic/reference/context-recovery.md 中的 Ambient Resume，并执行 comet resume-probe . --stdin --json。只有 auto_resume 会自动进入；对于 ask_user，根据 reason，使用 Ambient Resume 表中的问题和选项询问；out_of_scope/none 则不会进入。
• 开始新请求或目标变更不明确时：阅读 comet-classic/reference/intent-frame.md 中的最简示例和目标选择规则。列出活动变更，填写 CometIntentFrame，然后运行 comet classic intent route --stdin。Agent 从证据中提取意图字段；Runtime 负责计算路由。遵循其结果，不要另行编造一套文字评分规则。
• 目标变更明确且 Runtime 已初始化时，将其工作区绑定到下方所述位置。新的 SDK 变更使用 comet-state.yaml；历史 .comet.yaml 文件应原地读写，兼容模式初始化仍使用旧名称。选择恢复路径时，依据 state next 返回的 Runtime 所有权，而不是仅依据状态文件是否存在。存在多个活动变更且尚未选定目标时，不要提前绑定。真正的新变更应进入 /comet-open 或相应的预设 Skill，由其准备工作区后再进行初始化；对于未初始化的变更，workspace resolve 会报告未找到。

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

如果同一变更同时存在 comet-state.yaml 和 .comet.yaml（包括失效的符号链接），请停止操作，保留两者并检查其来源。不要默默选择其中一个、覆盖任一文件或自动重命名。

如果选择响应包含当前 Runtime 所有权、阶段、修订版本和 nextAction，请直接继续。只有在信息缺失、外部状态发生变化或响应已过期时，才运行 comet state next <change-name> --json。

请一并转移实际状态文件、变更文档、引用的工件、代码和项目配置。检查点不包含单独的子工作树或未提交代码。对于状态文件实际包含 run_checkpoint 的已复制 SDK 变更，通过命名的 state select 或 state next 恢复保存的阶段、Actions 和批准记录。继续外部工作前，请确认原设备上的执行流程已停止。重试前，先协调结果未知的 Action。只有当较旧的状态文件没有检查点，且常规入口明确报告缺少 Run 历史记录时，才检查正式文档；说明显式恢复会返回 Open，并需要重新获取批准和重新检查，然后在运行 comet state restore <change-name> --confirmed 前征得用户同意。

如果响应中已包含 agent.continuation.mode，请先遵循 comet-classic/reference/auto-transition.md 中的通用规则。使用 mode 来执行、等待、询问、协调或完成；下方按 nextAction.kind 路由的规则仅适用于不含 mode 的较旧响应。 使用 data.runtimeFormat 区分 sdk 和 compat，然后遵循返回的阶段、配置和 data.nextAction.kind。只有 SDK 的 action 才会加载返回的 Skill。对于 decision、evidence 或 reconcile，先解决当前 Run 的决策、证据或已声明的 Action；切勿将其作为新的 Skill action 重放。对于 compat 变更，保留原有路由。将新的完整变更发送给 /comet-open，由它准备工作区、创建 OpenSpec 工件并初始化 SDK Run。将已确认的 hotfix/tweak 选择发送给对应的预设 Skill。不要直接调用 /opsx:new。遇到所有权冲突或状态格式错误时，遵循 context-recovery.md 中的“Entry Errors and Recovery”并停止；不要根据工件推断阶段，也不要创建另一条状态记录。

创建工件前，必须先为新的完整变更选定工作区。完整工作流中的 isolation 可以是 current、branch 或 worktree；对于明确的并行工作请求，先准备 Worktree，否则遵循 comet-classic/reference/workspace.md。hotfix/tweak 会在各自的初始化过程中确认并绑定工作区。在绑定的工作区中恢复任务。如果分支所有权已变更，请根据用户确认的选择重新绑定；仅在缺少有效授权时才询问。

2. 加载当前阶段

对于相同任务，复用命令结果和上下文。根据返回的状态和 agent.continuation 继续；仅在缺少字段、工作区变更、恢复时上下文丢失或发生外部变更时查询。根据风险选择检查；Verify 负责对已完成的实现进行一次最终集成审查。

绑定工作区和阶段后，以及阶段变更、Agent 交接或上下文恢复时，遵循 任务上下文和工件语言。每次进入或恢复时，使用 continuation 或已声明 Action 的 contextRequest 获取一次快照。使用配置的工件语言，并且仅补充缺失的 Context Manifest 内容。报告实际使用情况，并在任务结束时保存检查点。

记忆学习仅提交可复用的用户信息；绝不将任务摘要、进度、命令输出或测试结果保存为个人记忆。任务完成前，按照任务上下文参考完成学习检查，并记录 submitted、no-observation 或 not-run。

项目经验和个人偏好应分别存储：任务完成前，使用 comet knowledge remember 将经项目验证且可复用的经验写入项目记忆；仅将用户偏好和稳定的协作习惯写入个人记忆。命令和筛选规则请参阅 任务上下文和工件语言。

运行时路由或阶段	入口和职责
new full / open	/comet-open：明确范围，创建所需产物，并获取用户的审查和确认
design	/comet-design：权衡技术方案并确认正式设计
build + full	/comet-build：恢复配置和计划，完成任务及所需审查
hotfix / build + hotfix	/comet-hotfix：修复现有的局部缺陷
tweak / build + tweak	/comet-tweak：在一次变更范围内进行轻量调整
verify	/comet-verify：执行验收检查、重新验证修复，并进行唯一一次最终集成审查
archive / verify_result: pass	/comet-archive：确认归档，仅提交本次变更的文件，并完成选定的交付方式

仅对新请求推荐轻量工作流。只有当风险符合预设且用户已明确选择时，才直接进入该流程。由 Agent 提出建议时，应说明原因，介绍 hotfix/tweak 和 full 各自的影响，并等待确认。绝不可悄然将现有 full 变更降级。应根据实际风险评估公共 API、数据迁移、安全性、并发和跨模块设计；文件数量少并不意味着可以省略必要步骤。

对于 hotfix/tweak，SDK 必须阅读并遵循预设范围，并复用有效的 rulings.md 授权；Compat 遵循所选预设的 reference/compat.md。若仅文件数量超出阈值，则审查范围，并且只在需要新决策时提问。用户做出选择后，使用 Run continuation 或匹配的 Compat 命令升级。使用 verify_mode 设置验证深度；工作流决策与升级决策应分开处理。

恢复会话、出现外部变更，或实际工作与计划、任务、审查或交付记录不一致时，请阅读 comet-classic/reference/context-recovery.md。使用当前阶段入口中的 nextAction 确定未完成的步骤。复用有效配置和已有工作；未勾选的任务并不能证明尚未完成实现。恢复流程应遵循该参考文档。

3. 完成本次调用已授权的工作

阶段退出检查通过后，遵循 comet-classic/reference/auto-transition.md：从成功结果中读取 agent.continuation，并仅加载其指向的下一个 Skill。只有在可复用状态不可用、会话恢复时缺少上下文，或外部状态发生变化时，才再次查询。auto_transition: false 控制的是下一次 Skill 调用，不是 Guard 已推进的阶段。若为 NEXT: manual，则显示 HINT 并结束本次调用，不要添加确认问题。

在用户明确作出答复前，依赖该决定的工作必须暂停。首次请求澄清或确认前，阅读 comet-classic/reference/decision-point.md，并遵循其中的选项、推荐理由、各选项的影响以及 AskUserQuestion 优先级。若该文档已在上下文中，则重复使用。自动交接或单一推荐方案不能跳过这些确认：

• 如果目标更改、PRD 拆分或工作区隔离仍需选择，应将相关问题一并询问并等待答复。
• 在 Open 结束时，获取对名称、范围和产物的最终确认。Design 提出方案后，获取对正式设计的确认。两种情况下，都要先提供可供审阅的结果，再等待批准或修改要求。
• Build 编写计划前，只有在执行、TDD 或审查配置缺失，或用户要求更改时，才询问相关配置。用户要求暂停在 plan-ready 后，等待其明确指示再继续。
• 在 Verify 中，如果要接受偏差、解决实现与 Spec 之间的分歧，或在达到自动修复上限后选择下一步，则应询问用户。在 Archive 中，确认归档及交付方式。
• 如果要将预设升级为完整工作流，或 Build 需要扩大范围、重新设计或拆分更改，则应询问用户。

在用户明确作出选择前，不要写入状态，也不要执行依赖该选择的分支操作；不得绕过阶段 Guard。重复使用有效的授权和配置。对于已知修复方式可处理的范围内失败、可依据证据协调的状态，以及只有一种有效操作的其他步骤，应自动处理；不要添加“继续吗？”之类的问题。

归档和交付方式合并为一次最终确认。/comet-archive 会检查授权、实际 Git 状态，以及所选交付操作是否已完成。验证通过并不代表已获准归档；归档目录也不能证明提交、推送或 PR 已完成。

每个阶段的规则

• 使用 Runtime 阶段、Guard 结果和当前工作区绑定来确定工作流状态。文件和对话有助于核对状态；它们不能授权手动编辑阶段以绕过确认或验证。
• proposal 记录目标和范围；spec 定义行为和验收标准；design_doc 指向唯一的正式技术设计；plan 描述实施方案；tasks.md 记录任务完成情况。
• 遵循已确认的执行、TDD 和审查配置。自主模式仍要求完整的工作流设计、规划、实际验证和独立审查。Build 会确认缺失的配置或用户要求的配置变更；切勿根据模型名称替换配置。
• 使用 comet-classic/reference/dirty-worktree.md 归属未提交的变更。只处理当前变更，并保护无关工作。对于被拒绝的状态更新、路径越界、依赖不可用或归属不明确的情况，请阅读“Entry Errors and Recovery”中的 comet-classic/reference/context-recovery.md，报告原始错误，并遵循相应的恢复规则。
• 对当前阶段的失败，请阅读 comet-classic/reference/debug-gate.md，并在修复前进行调查。只有实际运行后，才能声称测试或构建已成功。只有当 Runtime 确认先前的通过结果仍然有效时，才可复用该结果。

阅读 comet-classic/reference/comet-yaml-fields.md 以了解状态字段的含义，并阅读 comet-classic/reference/file-structure.md 以了解产物目录。仅在上述触发条件适用时，才阅读其他参考资料。