rpamis/comet

# Comet 双语文档

先读取 `../comet-github/references/maintainer-contract.md`，并将文档变更限制在用户要求的范围内。

## 确定源语义

1. 确认权威的行为、发布范围或已接受的中文措辞。
2. 先更新并审阅中文语义。翻译时不要静默改变已经确认的用户可见术语。
3. Skill 内容需要用户确认时，在中文版本完成后暂停；确认后再同步英文版本。
4. 明确要求发布同步时，保持主 Changelog 和中英文网站页面的用户可见语义及信息架构一致。

## 谨慎同步

- 除非变更确实需要，准确保留示例、命令名、配置键、链接、锚点和代码围栏。

# Comet GitHub

将本 Skill 作为 Comet GitHub 工作的明确入口。路由前先读取[共享维护者契约](references/maintainer-contract.md)。

## 按意图路由

- “审阅 PR / 看这个 PR” → `comet-github-pr-review`
- “看下这个 Issue 是否成立 / 是不是 Bug” → `comet-github-issue-triage`
- “把这个本地想法提成 Issue” → `comet-github-idea-to-issue`
- “CI 有报错 / 哪个 job 失败了” → `comet-github-ci-triage`
- “按照这个 Issue 修复” → `comet-github-issue-fix`

如果请求同时包含审阅和修复，先完成只读诊断，再说明建议交接到哪个流程。不得从分析阶段无声地跨入代码修改或 GitHub 写操作。

# Comet GitHub CI 分诊

先读取 `../comet-github/references/maintainer-contract.md`。默认只做诊断；只有用户要求时才实施修复。

## 检查准确的远端状态

1. 解析 PR，记录当前 head SHA 和目标分支。
2. 运行 `gh pr checks <pr> --json name,state,bucket,link,workflow,startedAt,completedAt`。
3. 对失败 job 使用 `gh run view <run-id> --log-failed` 或最小范围的 job 日志检查真实失败边界。不要在没有日志证据时相信聚合助手摘要。
4. 检查可合并状态，并确认显示的检查属于当前 head。过期 run 不能证明当前代码有问题。
5. Codecov 页面信息不完整时，通过可用 API 检查受影响文件和 patch coverage 元数据，并报告准确 head 和覆盖率范围。

## 分类失败原因

# Comet 本地想法转 GitHub Issue

先读取 `../comet-github/references/maintainer-contract.md`。起草阶段只读；创建 GitHub Issue 必须得到明确确认。

## 确定 Issue 内容

1. 理解本地观察，检查当前实现、测试、Runtime 路径和相关文档。
2. 按领域概念搜索已有 GitHub Issue 和 PR，判断这是重复问题、已有 Issue 的 follow-up，还是新报告。
3. 选择最匹配的仓库模板：bug、feature、task 或 question。起草字段前先读取当前 YAML 模板。
4. 区分用户可见问题和推测的实现原因。只有有助于复现或界定范围时才写入实现细节。

## 起草正文

生成以下内容：

# Comet GitHub Issue 修复

先读取 `../comet-github/references/maintainer-contract.md`。将 Issue 或 review 作为输入契约，不要把它当作修改 GitHub 或发布代码的授权。

## 确认工作边界

1. 阅读实时 Issue/PR，验证报告的问题确实存在。不要实施未经确认的 review bot 推测。
2. 确认目标分支、仓库状态、已有脏文件和关联 worktree。
3. 保护用户当前 checkout。目标分支或工作区较脏时，使用隔离的 worktree/branch。
4. 编辑前定义最小行为、文件、测试、生成资产、文档和非目标范围。

## 通过 Comet 所属流程实施

- Native 工作使用 Native workflow，Classic 工作使用 Classic workflow。

# Comet GitHub Issue 分诊

先读取 `../comet-github/references/maintainer-contract.md`。除非用户明确授权 GitHub 或代码变更，否则保持只读。

## 收集当前证据

1. 阅读完整 Issue 正文、评论、标签、作者、时间、关联 PR 和此前的分诊记录。
2. 按领域概念搜索已有 Issue，而不只是复用报告者的原文措辞。识别重复、被替代的 Issue 和已经实现的行为。
3. 检查当前源码、配置、安装路径、生成资产和相关测试，以实际仓库契约作为判断依据。
4. Bug 信息充分时复现最小有效路径。环境或凭证问题需要区分本地设置和产品行为。

不要仅因描述听起来合理就认定存在缺陷。报告可能有效、夸大、过期，或由本地安装/配置不一致造成。

## 分类结果

# Comet GitHub PR 审阅

先读取 `../comet-github/references/maintainer-contract.md`。除非用户另行授权修复或回复 GitHub，否则保持只读。

## 刷新目标状态

1. 解析 PR 编号或 URL，并确认仓库。
2. 获取当前 PR 元数据：目标分支、源分支和 SHA、作者、关联 Issue、标签、可合并状态和更新时间。
3. 阅读完整 PR 正文、提交、diff、评论和 review thread。确认 thread 是否已解决或过期，不要把所有可见评论都当作仍然有效。
4. 查询准确 head 对应的当前检查。如果有失败检查，将详细调查交给 `comet-github-ci-triage`。

结论必须基于当前 PR head/base。测试通过不能证明 PR 可合并，因为 head 可能落后于 base 或存在当前冲突。

## 审阅实现

# Comet 发布

先读取 `../comet-github/references/maintainer-contract.md`。本 Skill 负责准备发布资产；commit、push、tag、GitHub Release 和 npm 发布仍然需要单独授权。

## 确定发布范围

1. 阅读 `package.json`、lockfile 元数据、当前顶部 Changelog 标题、当前分支、`origin/master`、上一发布 tag 以及 release/hotfix 分支范围。
2. 判断当前分支是否已有高于 master 的版本。如果已有，就追加或重写同一个版本，不要创建重复版本。
3. 根据真实发布范围列出候选变更，只保留用户从上一版本升级后能够感知的内容。
4. 将条目分类为 Added、Changed、Fixed、Removed 或 Security。只有已发布基线中已经存在的用户问题才归入 Fixed。

## 编写发布内容

使用专业、中性、面向用户的英文 Changelog。描述行为和价值，不写实现过程、bundle/cache 细节、生成文件名、Git 对象 ID、review follow-up 或普通测试重构。

# Comet Runtime 诊断

先读取 `../comet-github/references/maintainer-contract.md`。修改源码或重新安装前，先完成诊断。

## 确定问题边界

将报告分类为以下一种或多种：

- 本地安装过期或不完整；
- 项目/全局配置或路径归属问题；
- 源码/Runtime 逻辑缺陷；
- 生成资产漂移；
- 平台注册、安装或卸载不一致；
- 文档或生命周期契约不一致。

# Comet 安全交付

先读取 `../comet-github/references/maintainer-contract.md`。只有用户明确授权后才执行 Git 交付动作；本 Skill 永远不会发布到 npm。

## 交付前检查

1. 记录当前分支、upstream、`git status --short --branch` 和 `git worktree list --porcelain`。
2. 检查 diff，确定准确的目标路径。如果与无关改动重叠，先确认范围。
3. 确认目标分支和 remote，不要静默切换分支或改变交付目标。
4. 涉及子模块时，先确认子模块自己的分支/状态；得到授权交付时，先提交子模块，再更新父仓库 gitlink。

## 暂存与验证

- 只暂存明确的目标路径；混合工作区中不要使用宽泛的暂存命令。

# Comet 入口

`/comet` 按项目配置选择 Native 或 Classic，再将用户请求交给相应的工作流 Skill 执行。

加载本 Skill 后，立即执行下方步骤。此时用户已选择使用 Comet，应继续处理请求，不再判断是否需要使用 Comet，也不能只给出不执行的理由。

1. 在当前项目运行 PATH 中安装的 Comet CLI：

   ```text
   comet workflow resolve . --activate --json
   ```

   若项目还没有 `.comet/config.yaml`，该命令会把全局默认配置保存到项目中，并创建对应的产物目录。此后修改全局默认值，不会覆盖这个项目已经保存的配置。

# Comet Any

根据用户目标调查真实 Skills，创作组合应用的正文、流程和业务实现。通过 `comet creator` 保存方案与进度，每完成一个阶段就读取当前动作，推进到完成、需要用户决定或外部能力阻塞。

Agent 编写入口 Skill、业务 Rule、执行端口与验证器；SDK 保留正文，追加执行协议和通用保护规则，并装配 Runtime。业务 Rule 描述业务约束，Runtime 与 Guard 控制动作、批准和写入权限。安装使用 SDK 正式分发。

## 开始或继续

1. 已知创作名称时运行 `comet creator status <name> --project <项目> --json`，再执行 `comet creator next <name> --project <项目> --json`。保留原名称与 Run；中断后先查询原 Action，不重复发起已完成工作。
2. 新创作先读取 `comet creator guide --project <项目> --json`。从用户描述确定目标与安装位置；只有无法调查且会改变结果的选择才询问用户。使用 `comet creator start <name> --project <项目> --goal <用户目标> --install-target <相对目录> --host codex|claude-code --json` 启动。
3. 首次领取或提交动作前，读取[创作动作与恢复](reference/sdk-creation.md)。使用返回的 Action、attempt、inputHash 和本次宿主会话标识；当前动作没有所需能力时明确阻塞，保留现场。

## 分析与方案

# Comet 阶段 5：归档（Archive）

首次进入阶段、交接给新 Agent 或上下文恢复后，读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言)，优先采用当前 continuation 或已领取 Action 的 `contextRequest`；同一阶段连续执行不重复获取。

收到入口返回的 layout 后，按 `comet-classic/reference/classic-layout.md` 确定各逻辑根对应的目录。当前上下文已有这份协议时，无需重复加载。本文件中的 OpenSpec CLI 调用均通过适配器执行，文件路径均基于已绑定的 `<classic-*>` 根目录，无需先额外运行 root show。

## SDK Run 路径

首次进入当前 SDK 阶段、换 Agent 或恢复上下文时，读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节；本会话已有且仍有效时直接复用。下文按当前阶段执行；`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。

优先复用同一 change、工作区和 Run 的最新有效响应中的 `agent.continuation`、`data.nextAction`、phase、revision 和路径摘要。只有冷恢复、工作区或外部状态变化、响应版本已过期或缺少当前步骤必要信息时，才运行 `comet state next <change-name> --json`；不要因加载下一 Skill 再读一次。后续写操作仍由 Runtime 校验当前版本与证据，不能用缓存跳过检查或批准。确认 `data.runtimeFormat: sdk`、phase 和 `nextAction.kind`，在已绑定的 `projectRoot` 执行；路径缺失或绑定发生变化时才运行 `comet classic workspace resolve <change-name> --json`。SDK Run 的 Verify 收据必须仍有效；状态文件和验证报告存在并不表示已获归档授权。`reconcile` 时运行 `comet state check <change-name> archive --recover --json` 核对原 Action 与磁盘、Git 证据，结果未明时不重做归档、提交、push 或 PR。

1. 复用当前有效的状态、工作区和证据摘要；缺少时运行 `comet state check <change-name> archive --json`。按 SDK 方法参考的 Archive 与 Git 交付章节 核对验证结论、当前绑定分支、归档影响和无关改动。需要推送或 PR 时，先确认 remote 和 PR base；多个可选目标不能猜测。用当前目标与效果摘要运行 `comet state propose-archive <change-name> --summary "<delivery-summary>"`，需要时附 `--remote <name>`、`--pr-base <branch>`。保存返回的 `data.wait.proposalHash` 为 `<proposalHash>`；恢复已有待决定 Wait 时复用它，不重复提案。
2. 按 decision-point.md 展示当前提案和 SDK 方法参考的 Archive 与 Git 交付选项。已有明确授权覆盖当前归档影响和相同交付目标时沿用；否则等待用户选择。用 `comet state decide-archive <change-name> --proposal-hash <proposalHash> --choice <local|push|pr|reverify|later>` 提交当前选择：local 仅归档并提交，push 再推送，pr 推送并创建 PR，reverify 返回 Verify，later 保留当前工作并停止本次调用。目标或 Verify 证据改变时重新核对并取得新的决定；旧提案哈希不能继续使用。

# Comet 阶段 3：计划与构建（Build）

首次进入阶段、交接给新 Agent 或上下文恢复后，读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言)，优先采用当前 continuation 或已领取 Action 的 `contextRequest`；同一阶段连续执行不重复获取。

收到入口返回的 layout 后，按 `comet-classic/reference/classic-layout.md` 确定各逻辑根对应的目录。当前上下文已有这份协议时，无需重复加载。本文件中的 OpenSpec CLI 调用均通过适配器执行，文件路径均基于已绑定的 `<classic-*>` 根目录，无需先额外运行 root show。

## SDK Run 路径

首次进入当前 SDK 阶段、换 Agent 或恢复上下文时，读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节；本会话已有且仍有效时直接复用。下文按当前阶段执行；`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。

优先复用当前有效结果中的 `agent.continuation` / `data.nextAction` 与已绑定状态；只有冷恢复、外部状态变化或缺少必要信息时，才运行 `comet state next <change-name> --json`。`data.runtimeFormat` 为 `sdk` 时，只按本节推进 Run；SDK 方法参考的执行策略选项、计划内容要求、实施与审查方法仍适用，状态和证据通过本节命令提交。`data.phase` 必须为 `build`。已有有效 layout 与当前配置时直接复用；缺少时运行 `comet state check <change-name> build --json`；若 `nextAction.kind` 为 `reconcile`，运行 `comet state check <change-name> build --recover --json` 核对原 Action 的结果，在结果明确前不重发外部工作。

先核对有效配置中的 `workflow` 或当前 `nextAction.stepId`。`tweak.build.*` / `workflow: tweak`：**立即执行：** 使用 Skill 工具加载 comet-tweak 技能。禁止跳过此步骤。`hotfix.build.*` / `workflow: hotfix`：**立即执行：** 使用 Skill 工具加载 comet-hotfix 技能。禁止跳过此步骤。技能加载后，传入同一 change、工作区、phase、Run revision 和 continuation，从该预设的 SDK Build 步骤继续，不要求 full Design Doc 或完整计划，也不重跑 Open。旧 Run 的原始 Action 仍可能引用 `comet-build`，同样按此规则路由。已批准升级且当前步骤为 `full.build.*` 时，执行下列 full 路径。

# Comet Classic — OpenSpec + Superpowers

Classic 分为 Open → Design → Build → Verify → Archive 五个阶段。OpenSpec 管理需求规格与归档，Superpowers 提供设计方法，以及用户选定的规划、执行和审查方法。完整流程（full）必须经过 brainstorming 和设计确认；hotfix/tweak 使用各自的预设步骤。

## 1. 确定目标与工作区

开始新任务或更换宿主时，必须读取并执行[宿主能力核对](../comet/reference/host-check.md)，在批准 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` 不进入。
- 启动新需求或目标 change 尚不明确时：读取 `comet-classic/reference/intent-frame.md` 的最小示例与目标选择规则，获取未归档的 change 列表后填写 CometIntentFrame，运行 `comet classic intent route --stdin`。Agent 只负责按证据填写意图字段，路由由 Runtime 计算；以返回结果为准，不另写一套自然语言评分规则。
- 已明确目标 change 且已由 Runtime 初始化时：按下方绑定工作区；SDK 新 change 使用 `comet-state.yaml`，历史 `.comet.yaml` 原地读写，compat 初始化仍使用旧名，以 `state next` 返回的 Runtime 归属判断恢复路径，不能只看状态文件是否存在。有多个未归档的 change 且尚未选定时，不提前绑定。真正的新 change 直接交 `/comet-open` 或对应预设 Skill，它们会先准备工作区再初始化；`workspace resolve` 对未初始化的 change 会报 not found。

# Comet 阶段 2：深度设计（Design）

首次进入阶段、交接给新 Agent 或上下文恢复后，读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言)，优先采用当前 continuation 或已领取 Action 的 `contextRequest`；同一阶段连续执行不重复获取。

收到入口返回的 layout 后，按 `comet-classic/reference/classic-layout.md` 确定各逻辑根对应的目录。当前上下文已有这份协议时，无需重复加载。本文件中的 OpenSpec CLI 调用均通过适配器执行，文件路径均基于已绑定的 `<classic-*>` 根目录，无需先额外运行 root show。

## SDK Run 路径

首次进入当前 SDK 阶段、换 Agent 或恢复上下文时，读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节；本会话已有且仍有效时直接复用。下文按当前阶段执行；`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。

优先复用同一 change、工作区和 Run 的最新有效响应中的 `agent.continuation`、`data.nextAction`、phase、revision 和路径摘要。只有冷恢复、工作区或外部状态变化、响应版本已过期或缺少当前步骤必要信息时，才运行 `comet state next <change-name> --json`；不要因加载下一 Skill 再读一次。后续写操作仍由 Runtime 校验当前版本与证据，不能用缓存跳过检查或批准。当 `data.runtimeFormat` 为 `sdk` 时，只执行本节的状态命令；设计探索、提问与正式文档要求见 SDK 方法参考的 Design 章节，状态操作使用本节命令。`data.phase` 必须为 `design`；已进入 Build 时交回当前阶段入口。`data.nextAction.kind` 为 `reconcile` 时，运行 `comet state check <change-name> design --recover --json` 核对已领取 Action 的原结果，在结果明确前停止，不重新提案或重发工作。

1. 待执行 Action 为 `full.design.handoff` 时，复用当前响应的 layout 与产物引用；缺少时才运行 `comet state check <change-name> design --json`，直接读取当前 OpenSpec proposal、tasks、delta specs 和已有 design.md 中本次设计需要的内容。按 SDK 方法参考的 Design 章节形成候选技术方案；此时还没有 SDK handoff 包，不执行旧 `comet handoff ... --write`，也不把手写摘要当作 SDK handoff。持续保存 `brainstorm-summary.md`，未确认内容标为候选。
2. 如候选方案需要 Spec Patch，先按 SDK 方法参考的设计确认规则向用户说明具体补丁并取得明确同意，再修改 delta spec。范围发生实质变化时重新澄清。待 OpenSpec 来源稳定后，执行 `comet state propose-design <change-name> --proposal "<candidate-summary>"`，其中摘要必须覆盖将请用户确认的方案、关键取舍、风险和 Spec Patch；保存返回的 `data.wait.proposalHash` 为 `<proposalHash>`。此命令生成并记录可追溯的 handoff；优先使用提案结果中的 `data.configuration.handoffContext`，缺少时再运行 `comet state next <change-name> --json`；读取 `data.configuration.handoffContext` 对应的 Markdown 包，核对它与候选方案及当前源文件一致。用户尚未决定时，恢复应复用这个 Wait，不重复运行 propose-design。

# Comet 预设路径：Hotfix

开始或恢复任务前，必须先读取并遵守 `comet-classic/reference/classic-layout.md`。本文件中的 OpenSpec CLI 调用必须通过适配器执行，文件路径必须基于该协议绑定的 `<classic-*>` 逻辑根目录。

快速缺陷修复流程：open → build → 根因消除检查 → verify → archive。跳过 brainstorming 和完整实施计划，适用于修复已有行为、不需要设计新功能的场景。

**适用条件**（必须全部满足）：

1. 修复已有功能的缺陷，不新增功能
2. 不涉及接口变更或架构调整
3. 改动范围可预估（文件数仅作提示，不会自动要求升级，见 SDK 方法参考的预设范围复核）

**不适用**：修复过程中如发现 SDK 方法参考的预设范围复核列出的变化，需要由用户决定是否改用完整 `/comet-classic` 流程。

# Comet 语义记忆评审

你是固定的第一方记忆评审器。只做语义筛选，不写文件、不调用工具、不扫描仓库，也不修改任何 Skill、规则或 Agent 指令。

## 输入边界

只读取 Runtime 传入的 `comet.memory.review.v1` `MemoryReviewPacket`：配置语言、项目身份、workflow/change、可信检查点、少量用户证据、相关记忆、evidence 和预算。不要要求或推测完整对话、日志、diff、仓库内容或隐藏推理。

## 判断顺序

1. 先处理用户明确的“记住/以后都这样/改成/忘掉”。明确记忆优先，不能被隐式行为覆盖；直接用户文本保持原文，不翻译。
2. 只保留未来可复用且不易从仓库重查的个人偏好、协作习惯、输出方式或已验证个人经验。
3. 跳过一次性命令、测试/提交/Issue/PR 摘要、流水账、普通源码事实、猜测、原始日志、完整 diff、完整 transcript 和无后续收益的内容。
4. 整个 `actions` 集合只能使用一个 scope：所有真正的动作要么全部是 `global`，要么全部是 `project`，绝不能混用；无法保持单一 scope 时返回唯一 `skip`。自动行为默认是 `project`；只有 packet 明确提供跨项目一致成功证据时才可选择 `global`。不要自行创造证据或项目身份。

# Comet Native

Native 在项目中保存需求和验收结论。先确认 change 的运行格式，再执行当前动作。

## 必须遵守的规则

- 已确认范围内的实现、文档修复、证据复用和恢复连续推进；只在需要新决定、授权或外部信息时暂停。使用最新 continuation 的命令、模板和任务包，修正输入后沿用当前任务。
- 以磁盘上的 `.comet/config.yaml`、当前 change 的 `comet-state.yaml`、Runtime 返回的进度，以及正式文件为准，聊天记忆只作辅助。工作流保存的正式文件中，Agent 只编辑 brief、完整目标 Spec、关联时的 `delta.yaml` 和 `children.yaml`；状态、检查结果、报告、锁和事务由 Runtime 管理。
- 通过 PATH 中公开的 `comet native` 命令推进，用户不手工执行命令。命令不可用时报告安装不完整并停止；参数以 `comet native <command> --help` 为准。
- 新建 change 走 CLI 并使用响应路径；拒绝后按信息中的命令或目标修正并重试；自定义 Hook、非 Comet 工作和普通同名文件保持中立。
- Builder 提交本轮待验收的代码和相关文件，称为“候选实现”。每轮都由新的只读 Verifier 独立判断全部验收项。判断全部验收项不等于重跑全部命令：仍与当前候选实现匹配的 Runtime 检查记录可以复用，只补充缺失或失效的检查。失败、阻塞、未执行和超时不能算通过。
- 只有用户明确确认完整 Shape、接受最终结果或选择相应交付方式后，才执行对应的确认命令。沿用已确认的需求范围和 Runtime 保存的用户选择。归档、merge、push、PR 和工作区清理各自需要的授权不能互相代替。
- Native 主流程由本 Skill 和 Runtime 完成，不依赖外部 Skill；不改变已确认的需求和约束时，实现方法由 Agent 自行选择。

# Comet 阶段 1：开启（Open）

首次进入阶段、交接给新 Agent 或上下文恢复后，读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言)，优先采用当前 continuation 或已领取 Action 的 `contextRequest`；同一阶段连续执行不重复获取。

开始或恢复任务前，必须先读取并遵守 `comet-classic/reference/classic-layout.md`。本文件中的 OpenSpec CLI 调用必须通过适配器执行，文件路径必须基于该协议绑定的 `<classic-*>` 逻辑根目录。

## 前置条件

- 无活跃 change，或用户希望创建新 change

## 步骤

### 0. 设置输出语言

# Comet 手动代码审查

对当前选中的 Comet change 执行一次按需、只读的代码审查。这个入口不属于任何阶段，也不替代 Build 或 Verify 的验证和审查。

本入口独立于 `review_mode`。`review_mode` 控制流程内的自动审查策略，`/comet-review` 则由用户手动触发，只执行一次审查；调用本入口不得读取、修改或覆盖当前 change 的 `review_mode`。

## 只执行读取和审查操作

本 Skill 的整个调用必须保持只读：

- 不修改、创建或删除文件；
- 不暂存、提交、切换分支、创建分支或创建 worktree；
- 不运行 `comet state select`、`comet native select`、`comet state set`、`comet state transition`、阶段守卫、`comet native next` 或归档命令；
- 不修复发现的问题，不推进 phase，不更新 tasks、状态、验证报告或审查记录；

# Comet 预设路径：Tweak

开始或恢复任务前，必须先读取并遵守 `comet-classic/reference/classic-layout.md`。本文件中的 OpenSpec CLI 调用必须通过适配器执行，文件路径必须基于该协议绑定的 `<classic-*>` 逻辑根目录。

Tweak 为 Comet 五阶段流程提供一组预设配置。它通过 OpenSpec 完成需求与实施工作，复用 open、build、verify、archive 阶段，跳过 Superpowers brainstorming 和完整实施计划，不另建一套独立流程。

适用于配置调整、文档或提示词优化等轻量改动，也适用于需要依据 spec（含 delta spec）实施、但不需要完整 `/comet-classic` 深度设计的中等变更。Tweak 正常支持 delta spec，不能仅因为需要 delta spec 就要求升级流程。

**适用条件**（必须全部满足）：

1. 可以在**单个 OpenSpec change** 中完成
2. 无需通过 Superpowers Design Doc 和完整实施计划，就能明确方案
3. 不涉及跨模块、跨层级的架构协调
4. 任务规模可预估（文件数和任务数仅作提示，不会自动要求升级，见 SDK 方法参考的预设范围复核）

# Comet 阶段 4：验证（Verify）

首次进入阶段、交接给新 Agent 或上下文恢复后，读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言)，优先采用当前 continuation 或已领取 Action 的 `contextRequest`；同一阶段连续执行不重复获取。

收到入口返回的 layout 后，按 `comet-classic/reference/classic-layout.md` 确定各逻辑根对应的目录。当前上下文已有这份协议时，无需重复加载。本文件中的 OpenSpec CLI 调用均通过适配器执行，文件路径均基于已绑定的 `<classic-*>` 根目录，无需先额外运行 root show。

## SDK Run 路径

首次进入当前 SDK 阶段、换 Agent 或恢复上下文时，读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节；本会话已有且仍有效时直接复用。下文按当前阶段执行；`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。

优先复用同一 change、工作区和 Run 的最新有效响应中的 `agent.continuation`、`data.nextAction`、phase、revision 和路径摘要。只有冷恢复、工作区或外部状态变化、响应版本已过期或缺少当前步骤必要信息时，才运行 `comet state next <change-name> --json`；不要因加载下一 Skill 再读一次。后续写操作仍由 Runtime 校验当前版本与证据，不能用缓存跳过检查或批准。确认 `data.runtimeFormat: sdk`、`data.phase: verify` 和 `nextAction.kind`，在已绑定的 `projectRoot` 执行。路径缺失或绑定发生变化时才运行 `comet classic workspace resolve <change-name> --json`；缺少当前任务、工作区或证据摘要时才运行 `comet state check <change-name> verify --json`。`reconcile` 时改用 `comet state check <change-name> verify --recover --json` 查明原 Action 和检查结果；结果未明时停止，不重复执行外部检查。

1. 按 SDK 方法参考的风险评估、最终集成审查和 light/full 验证方法检查当前 change，但以 SDK Run 的状态和证据为准；不调用旧 `state scale`、`state set`、`comet handoff` 或旧 `comet check` 证据路径。实施或任务记录需要修复时，先报告具体失败项；只有当前待执行的是 `<profile>.verify.run`（`<profile>` 为 full、hotfix 或 tweak），才运行 `comet state transition <change-name> verify-fail --reason "<failure-reason>"`。此命令将失败原因作为同一 Run 的 Verify Action 结果并返回 Build；按同次响应的当前 Build Action 继续；缺少续行信息时才读取 `state next --json`。已有检查失败或结果未明时先读取其 Action，不另报一次 Verify 失败。
2. 验证结论合格后，将实际检查项、证据引用、独立审查结论及可接受偏差写入仓库内的验证报告 `<report-ref>`。以明确的完整验证命令直接运行 `comet guard <change-name> verify --report <report-ref> --apply -- <program> [args...]`。Guard 在同一 Run 中提交报告 Action、报告证据和真实检查收据；不能用手工声明代替检查。检查失败后读取同次响应的失败收据和当前 Build/Verify Action；缺少时才读取 `state next --json`，按最新 Action 处理，不将失败解释为通过。

# Comet Entry

`/comet` selects Native or Classic from project configuration, then passes the request to that workflow's Skill.

Once this Skill is loaded, immediately follow the steps below. The user has already chosen Comet: continue their request without reconsidering whether to use it or merely explaining why you would not proceed.

1. Run the Comet CLI installed on PATH in the current project:

   ```text
   comet workflow resolve . --activate --json
   ```

   If the project has no `.comet/config.yaml`, this command saves the global defaults in the project and creates the configured artifact directories. Later changes to global defaults do not overwrite this project's saved configuration.

# Comet Any

Investigate real Skills for the user's goal, then author the application's documents, workflow, and business implementation. Use `comet creator` to preserve the plan and progress. After each stage, read the current action and continue until completion, a user decision, or an external capability blocker.

The Agent writes the entry Skill, business Rule, execution ports, and validators. The SDK preserves the documents, appends execution protocol and common protection rules, and assembles Runtime. Business Rules describe business constraints; Runtime and Guard control actions, approval, and write permissions. Installation uses formal SDK distribution.

## Start or resume

1. When the creation name is known, run `comet creator status <name> --project <project> --json`, then `comet creator next <name> --project <project> --json`. Preserve the original name and Run; after interruption, inspect the original Action and do not repeat completed work.
2. For a new creation, read `comet creator guide --project <project> --json`. Determine the goal and installation location from the user's description; ask only about choices that cannot be investigated and would change the result. Start with `comet creator start <name> --project <project> --goal <user-goal> --install-target <relative-directory> --host codex|claude-code --json`.
3. Before the first claim or action submission, read [Creation actions and recovery](reference/sdk-creation.md). Use the returned Action, attempt, inputHash, and the current host session identifier; when the current action lacks a required capability, report the blocker and preserve the current work.

## Analysis and plan

# Comet Phase 5: Archive

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.

After entry returns layout, follow `comet-classic/reference/classic-layout.md` to bind each logical root to its directory. Do not reload the protocol if it is already in context. Use the adapter for OpenSpec CLI calls and the bound `<classic-*>` roots for paths; do not run an extra root show first.

## SDK Run path

On first entering the current SDK phase, handing off to a new Agent, or restoring context, read [phase entry and recovery](../comet-classic/reference/sdk-methods.md#phase-entry-and-recovery) and the current phase's section in that reference. Reuse them when already available and still valid in this session. Continue with the phase below; recovery routes based on `nextAction.kind` apply only to older responses without a continuation mode.

Reuse the latest valid response for the same change, workspace, and Run: `agent.continuation`, `data.nextAction`, phase, revision, and path summaries. Run `comet state next <change-name> --json` only for cold recovery, workspace or external state changes, a stale response version, or missing information needed for the current step; loading the next Skill is not a reason to query again. Runtime still validates current versions and evidence on writes; cached context cannot bypass checks or approval. Confirm `data.runtimeFormat: sdk`, phase, and `nextAction.kind`, and work in the bound `projectRoot`; run `comet classic workspace resolve <change-name> --json` only when paths are missing or the binding has changed. Verify receipts must still be valid; the state file and a report file do not authorize delivery. For `reconcile`, use `comet state check <change-name> archive --recover --json` to inspect the original Action and disk/Git evidence. Do not repeat archive, commit, push, or PR while the result is unknown.

1. Reuse current valid state, workspace, and evidence summaries; run `comet state check <change-name> archive --json` only when they are missing. Under SDK execution methods, inspect verification, the bound branch, archive impact, and unrelated edits. For push or PR, confirm remote and PR base; do not guess among alternatives. Run `comet state propose-archive <change-name> --summary "<delivery-summary>"`, adding `--remote <name>` and `--pr-base <branch>` as needed. Save `data.wait.proposalHash` as `<proposalHash>`. Reuse an existing pending Wait.
2. Present the current proposal and delivery options under decision-point.md and the Archive and Git delivery section of SDK execution methods. Reuse explicit authorization covering the current archive effects and same delivery target; otherwise await the user choice. Run `comet state decide-archive <change-name> --proposal-hash <proposalHash> --choice <local|push|pr|reverify|later>`: local archives and commits, push additionally pushes, pr pushes and creates the PR, reverify returns to Verify, and later preserves work and stops this invocation. Recheck and obtain a new decision if target or Verify evidence changes; never reuse a stale proposal hash.

# Comet Phase 3: Plan and Build

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.

After entry returns layout, follow `comet-classic/reference/classic-layout.md` to bind each logical root to its directory. Do not reload the protocol if it is already in context. Use the adapter for all OpenSpec CLI calls and the bound `<classic-*>` roots for paths; do not run an extra root show first.

## SDK Run path

On first entering the current SDK phase, handing off to a new Agent, or restoring context, read [phase entry and recovery](../comet-classic/reference/sdk-methods.md#phase-entry-and-recovery) and the current phase's section in that reference. Reuse them when already available and still valid in this session. Continue with the phase below; recovery routes based on `nextAction.kind` apply only to older responses without a continuation mode.

Reuse the current valid result's `agent.continuation` / `data.nextAction` and bound state. Run `comet state next <change-name> --json` only on a cold resume, after external state changes, or when necessary information is missing. For `data.runtimeFormat: sdk`, advance only this Run; the implementation methods, plan content, and reviews are in SDK execution methods; submit state and evidence through this section. `data.phase` must be `build`. Reuse valid layout and configuration already in context; use `comet state check <change-name> build --json` only when they are missing. For `nextAction.kind: reconcile`, run `comet state check <change-name> build --recover --json` and establish the original outcome before repeating external work.

First check `workflow` in the valid configuration or the current `nextAction.stepId`. For `tweak.build.*` / `workflow: tweak`, **Immediately execute:** Use the Skill tool to load the comet-tweak skill. Skipping this step is prohibited. For `hotfix.build.*` / `workflow: hotfix`, **Immediately execute:** Use the Skill tool to load the comet-hotfix skill. Skipping this step is prohibited. After the skill loads, pass the same change, workspace, phase, Run revision, and continuation and resume its SDK Build step. Do not require a full Design Doc or implementation plan, or repeat Open. Older Runs may still store `comet-build` as the raw Action reference; route them the same way. After an approved upgrade, use the full path in SDK execution methods when the current step is `full.build.*`.

# Comet Classic — OpenSpec + Superpowers

Classic has five phases: Open → Design → Build → Verify → Archive. OpenSpec manages specifications and archiving. Superpowers provides design methods and the planning, execution, and review methods selected by the user. The full workflow requires brainstorming and design confirmation; hotfix/tweak follow their preset steps.

## 1. Resolve the Target and Workspace

For a new task or host change, perform the [host capability check](../comet/reference/host-check.md) before approving Open. When execution configuration changes, check only capabilities required by the new strategy.

Before starting or resuming, resolve artifact paths with `comet-classic/reference/classic-layout.md` and follow “CLI Bootstrap” in `comet-classic/reference/scripts.md`. Use the public Comet CLI and its OpenSpec adapter. Read only sections needed for the current action; reuse valid instructions already in context.

- When Classic was not explicitly invoked and existing work may need to resume: read Ambient Resume in `comet-classic/reference/context-recovery.md` and follow `comet resume-probe . --stdin --json`. Only `auto_resume` enters automatically; for `ask_user` ask by `reason` using the Ambient Resume table's question and options; `out_of_scope`/`none` does not enter.
- When starting a new request or the target change is unclear: read the minimal example and target-selection rules in `comet-classic/reference/intent-frame.md`. List active changes, fill a CometIntentFrame, and run `comet classic intent route --stdin`. The Agent extracts intent fields from evidence; Runtime computes the route. Follow its result without inventing a separate set of prose scoring rules.
- When the target change is explicit and Runtime has initialized it, bind its workspace below. New SDK changes use `comet-state.yaml`; historical `.comet.yaml` files are read and written in place, and compat initialization still uses the old name. Use Runtime ownership returned by `state next`, not the mere presence of the state file, to choose the recovery path. Bind only after selecting among active changes. A new change goes to `/comet-open` or the matching preset Skill, which prepares the workspace before initializing; `workspace resolve` reports not-found for an uninitialized change.

# Comet Phase 2: Design

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.

After the entry returns layout, use `comet-classic/reference/classic-layout.md` to resolve each logical root. Reuse this protocol if it is already in context. Route all OpenSpec CLI calls through the adapter and use the bound `<classic-*>` roots for file paths; do not run an extra root show first.

## SDK Run path

On first entering the current SDK phase, handing off to a new Agent, or restoring context, read [phase entry and recovery](../comet-classic/reference/sdk-methods.md#phase-entry-and-recovery) and the current phase's section in that reference. Reuse them when already available and still valid in this session. Continue with the phase below; recovery routes based on `nextAction.kind` apply only to older responses without a continuation mode.

Reuse the latest valid response for the same change, workspace, and Run: `agent.continuation`, `data.nextAction`, phase, revision, and path summaries. Run `comet state next <change-name> --json` only for cold recovery, workspace or external state changes, a stale response version, or missing information needed for the current step; loading the next Skill is not a reason to query again. Runtime still validates current versions and evidence on writes; cached context cannot bypass checks or approval. For `data.runtimeFormat: sdk`, use this section for state changes; use the Design section of SDK execution methods for exploration, questions, and formal document requirements. `data.phase` must be `design`. If Build has begun, return to its entry. For `nextAction.kind: reconcile`, run `comet state check <change-name> design --recover --json` and establish the claimed Action's original outcome before proposing or redispatching.

1. At `full.design.handoff`, reuse layout and references from the current response; run `comet state check <change-name> design --json` only when they are missing. Read the current OpenSpec proposal, tasks, delta specs, and relevant existing design.md. Develop candidate solutions under the Design section of SDK execution methods and keep `brainstorm-summary.md` current, marking unapproved content as a candidate. There is no SDK handoff packet yet; do not call legacy `comet handoff ... --write` or substitute a handwritten summary.
2. For a needed Spec Patch, explain it and obtain explicit agreement under the Design confirmation rules in SDK execution methods before editing the delta spec. Reclarify material scope changes. When sources are stable, run `comet state propose-design <change-name> --proposal "<candidate-summary>"`; the summary must cover the proposed design, tradeoffs, risks, and Spec Patch. Save `data.wait.proposalHash` as `<proposalHash>`. This creates the traceable handoff. Use `data.configuration.handoffContext` from the proposal response, querying `comet state next <change-name> --json` only if it is missing, and verify the Markdown packet matches the candidate and source files. Reuse an existing pending Wait on recovery.

# Comet Preset: Hotfix

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

A short defect-repair flow: open → build → root cause check → verify → archive. It skips brainstorming and a full implementation plan, and applies to repairing existing behavior without designing new features.

**All applicability conditions must hold:**

1. Repair an existing feature's defect without adding a feature.
2. No interface changes or architectural redesign.
3. The scope can be estimated. File counts are only a prompt for review, not an automatic escalation rule; see “Escalation decisions.”

**When the preset may no longer fit:** If the repair encounters changes listed under “Escalation decisions,” let the user decide whether to use the full `/comet-classic` flow.

# Comet Semantic Memory Review

You are a fixed first-party memory reviewer. You only filter meaning. Do not write files, call tools, scan repositories, or modify any Skill, rule, or agent instruction.

## Input boundary

Read only the Runtime-provided `comet.memory.review.v1` `MemoryReviewPacket`: configured language, project identity, workflow/change, trusted checkpoint, small user evidence, relevant memories, evidence, and budget. Do not request or infer the full conversation, logs, diff, repository contents, or hidden reasoning.

## Decision order

1. Handle explicit user requests first: “remember”, “always do this”, “change it to”, or “forget”. Explicit memory wins and cannot be overwritten by inferred behavior; preserve direct user text without translation.
2. Keep only reusable personal preferences, collaboration habits, output preferences, or verified personal experience that is not easy to rediscover from the repository.
3. Skip one-off commands, test/commit/Issue/PR summaries, activity logs, ordinary source facts, guesses, raw logs, complete diffs, complete transcripts, and content with no future value.
4. The entire `actions` collection must use one scope: all real actions must be either `global` or `project`, never a mixture; if a single scope cannot be maintained, return the one `skip`. Automatic behavior defaults to `project`; choose `global` only when the packet provides consistent successful evidence across projects. Never invent evidence or project identity.

# Comet Native

Identify runtime format before acting; Runtime stores requirements and acceptance in the project.

## Required rules

- Continue confirmed implementation, document repairs, evidence reuse, and recovery. Pause for new decisions, authorization, or external information. Use current continuation commands, templates, and packages; correct inputs within the same task.
- Treat `.comet/config.yaml`, the current change's `comet-state.yaml`, Runtime progress, and formal artifacts on disk as authoritative; chat memory is supplementary. Among formal workflow files, the Agent edits only the brief, complete target Specs, association `delta.yaml`, and `children.yaml`. Runtime owns state, check results, reports, locks, and transactions.
- Advance through the public `comet native` CLI on PATH; do not ask the user to run commands manually. If the command is unavailable, report an incomplete installation and stop. Consult `comet native <command> --help` for arguments.
- Create changes with the CLI; use returned paths and follow denial commands or targets before retrying. Custom and non-Comet writes stay neutral.
- The Builder submits code as the candidate implementation. Each iteration requires a new read-only Verifier to assess every acceptance item independently. Assessing every item does not mean rerunning every command: reuse Runtime check records that still match the current candidate and add only missing or invalidated checks. Failed, blocked, unexecuted, and timed-out work cannot count as passed.
- Run confirmation commands only after the user explicitly confirms the complete Shape, accepts the final result, or selects the relevant delivery option. Reuse confirmed scope and user choices saved by Runtime. Authorization for Archive, merge, push, PR creation, and workspace cleanup is not interchangeable.
- This Skill and Runtime provide the Native workflow without an external Skill dependency. The Agent chooses implementation methods that preserve confirmed requirements and constraints.

# 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

# Comet Manual Code Review

Perform one on-demand, read-only code review of the currently selected Comet change. This entry is not a workflow phase and does not replace Build or Verify checks and reviews.

This entry is independent of `review_mode`. That field controls automatic reviews within the workflow; `/comet-review` is a single review explicitly requested by the user. Do not read, modify, or override the current change's `review_mode` during this invocation.

## Perform read-only operations

The entire Skill invocation must remain read-only:

- Do not modify, create, or delete files.
- Do not stage, commit, switch branches, create branches, or create worktrees.
- Do not run `comet state select`, `comet native select`, `comet state set`, `comet state transition`, phase guards, `comet native next`, or archive commands.
- Do not fix findings, advance phase, or update tasks, state, verification reports, or review records.

# Comet Preset: Tweak

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

Tweak provides preset choices for Comet's five-phase workflow. It uses OpenSpec for requirements and implementation, reuses open/build/verify/archive, and skips Superpowers brainstorming and a full implementation plan. It does not create a separate workflow.

Use it for configuration, documentation, or prompt adjustments, and moderate changes that need spec-driven implementation, including delta spec, without the full `/comet-classic` deep-design flow. Delta spec is a normal Tweak artifact; needing it is not by itself a reason to escalate.

**All applicability conditions must hold:**

1. The work fits in **one OpenSpec change**.
2. The solution can be clarified without a Superpowers Design Doc and full implementation plan.
3. No cross-module or cross-layer architectural coordination is needed.
4. Task scope can be estimated. File/task counts are prompts only, not automatic escalation rules; see “Escalation decisions.”

# Comet Phase 4: Verify

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.

After entry returns layout, follow `comet-classic/reference/classic-layout.md` to bind each logical root to its directory. Do not reload the protocol if it is already in context. Use the adapter for OpenSpec CLI calls and the bound `<classic-*>` roots for paths; do not run an extra root show first.

## SDK Run path

On first entering the current SDK phase, handing off to a new Agent, or restoring context, read [phase entry and recovery](../comet-classic/reference/sdk-methods.md#phase-entry-and-recovery) and the current phase's section in that reference. Reuse them when already available and still valid in this session. Continue with the phase below; recovery routes based on `nextAction.kind` apply only to older responses without a continuation mode.

Reuse the latest valid response for the same change, workspace, and Run: `agent.continuation`, `data.nextAction`, phase, revision, and path summaries. Run `comet state next <change-name> --json` only for cold recovery, workspace or external state changes, a stale response version, or missing information needed for the current step; loading the next Skill is not a reason to query again. Runtime still validates current versions and evidence on writes; cached context cannot bypass checks or approval. Confirm `data.runtimeFormat: sdk`, `data.phase: verify`, and `nextAction.kind`, and work in the bound `projectRoot`. Run `comet classic workspace resolve <change-name> --json` only when paths are missing or the binding has changed; use `comet state check <change-name> verify --json` only when current task, workspace, or evidence summaries are missing. For `reconcile`, use `comet state check <change-name> verify --recover --json` to investigate the original Action and check; stop if its result remains unknown.

1. Follow the risk assessment, integrated review, and light/full verification methods in SDK execution methods, but use the SDK Run as evidence authority. Do not call legacy `state scale`, `state set`, `comet handoff`, or `comet check` evidence commands. For implementation or task defects, report the specific failure. Only when `<profile>.verify.run` is pending (`<profile>` is full, hotfix, or tweak), run `comet state transition <change-name> verify-fail --reason "<failure-reason>"`. It records a failed Verify Action and returns to Build. Follow the current Build Action from that response; query `state next --json` only if continuation information is missing. Investigate existing failed or unknown checks before reporting another failure.
2. When verification passes, write actual checks, evidence references, independent review, and acceptable deviations in a repository report at `<report-ref>`. Run directly `comet guard <change-name> verify --report <report-ref> --apply -- <program> [args...]` with an explicit complete verification command. Guard records the report, evidence, and real check receipt in one Run; a manual claim is insufficient. On check failure, use the failure receipt and current Build or Verify Action from the same response; query `state next --json` only if they are missing, and follow the latest Action.

# Grill Test

用户明确选择这条链路时使用。先读取[执行与恢复](references/execution.md)，沿同一 SDK 根 Run 和当前子 Run 执行。

## 原始 Skill 的职责

1. grill：加载固定的 grill-me 原文；它仅要求执行 grilling 会话，没有文件输出。

   **立即执行：** 使用 Skill 工具加载 grilling 技能。禁止跳过此步骤。

   技能加载后，按原始 design tree/frontier 规则访谈。环境事实由子 Agent 调查，实际决定询问用户并等待回答。frontier 为空后，请用户确认共同理解。保留真实会话，并将会话摘要回传 SDK grill Action；通过该子 Run 的 confirm-understanding Wait 保存理解确认。此阶段不创建 brief 或其他业务文档，不借用 Native 的阶段产物。

2. to-spec：读取固定的 to-spec 原文，综合已确认的会话和代码事实，不再次访谈已有决定。按原模板七个章节生成第一份正式文档，确认测试 seams，发布至本地 tracker 的 .scratch/grill-test/spec.md。通过 confirm-spec 保存实际确认。

Two-axis review of the diff between `HEAD` and a fixed point the user supplies:

- **Standards** — does the code conform to this repo's documented coding standards?
- **Spec** — does the code faithfully implement the originating issue / spec?

Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.

The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.

## Process

### 1. Pin the fixed point

Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.

Run a `/grilling` session.

Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.

Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.

Each question should be formatted like so:

```
❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>

➡<U+FE0F> <your recommended answer>
```

Each round the user answers reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.

Implement the work described by the user in the spec or tickets.

Use /tdd where possible, at pre-agreed seams.

Run typechecking regularly, single test files regularly, and the full test suite once at the end.

Once done, use /code-review to review the work.

Commit your work to the current branch.

# Setup Matt Pocock's Skills

Scaffold the per-repo configuration that the engineering skills assume:

- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
- **Triage labels** — the strings used for the five canonical triage roles
- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

## Process

### 1. Explore

# Test-Driven Development

TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.

When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.

## What a good test is

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.

See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.

## Seams — where tests go

This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.

The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.

## Process

1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.

2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

Check with the user that these seams match their expectations.

3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.

# To Tickets

Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.

The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.

## Process

### 1. Gather context

Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.

### 2. Explore the codebase (optional)

# Comet — OpenSpec + Superpowers Dual-Star Development Workflow

OpenSpec and Superpowers orbit the same goal like a binary star system.

```
OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
Superpowers handles HOW — technical design, planning, execution, closing
```

**Core principle: brainstorming cannot be skipped. Every change must undergo deep design (except hotfix and tweak presets).**

---

## Decision Core

# Comet Phase 5: Archive (Archive)

## Prerequisites

- Verification passed (Phase 4 complete)
- Branch handled
- `verify_result: pass` in `openspec/changes/<name>/.comet.yaml`

## Steps

### 0. Output Language Constraint

Archive summaries and lifecycle closure notes must use the language of the user request that triggered this workflow.

# Comet Phase 3: Plan and Build (Build)

## Prerequisites

- Design Doc has been created (Phase 2 complete)
- Active change exists

## Steps

### 0. Entry State Verification (Entry Check)

Execute entry verification:

```bash

# Comet Phase 2: Deep Design (Design)

## Prerequisites

- Active change exists (proposal.md, design.md, tasks.md)
- No Design Doc (no corresponding file under `docs/superpowers/specs/`)

## Steps

### 0. Entry State Verification (Entry Check)

Execute entry verification:

```bash

# Comet Preset Path: Hotfix

Quick bug fix workflow: open → build → verify → archive. Skip brainstorming and full plan, applicable for behavior fixes not involving new capability design.

**Applicable conditions** (all must be met):
1. Fix bugs in existing functionality, no new capability
2. No interface changes or architecture adjustments
3. Change scope is predictable (usually ≤ 2 files)

**Not applicable**: If fix process discovers need for architecture adjustments, should upgrade to full `/comet` workflow.

---

## Process (preset workflow, 6 steps)

# Comet Phase 1: Open

## Prerequisites

- No active change, or user wants to create a new change

## Steps

### 0. Output Language Constraint

Every prompt and artifact request passed to OpenSpec must include the output-language constraint: use the language of the user request that triggered this workflow. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.

### 1. Explore Ideas and Clarify Requirements

# Comet Preset Path: Tweak

Tweak is a preset workflow of Comet's five-phase capabilities, not an independent parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.

Applicable for non-bug small scope changes, such as copy adjustment, configuration adjustment, documentation or prompt local optimization.

**Applicable conditions** (all must be met):
1. No new capability
2. No architecture changes
3. No interface changes
4. Typically no more than 3 tasks (file count constraint see upgrade conditions below)

**Not applicable**: If change process discovers need for capability, architecture or interface adjustments, should upgrade to full `/comet` workflow.

# Comet Phase 4: Verify and Close (Verify)

## Prerequisites

- Code committed (Phase 3 complete)
- All tasks.md tasks completed

## Steps

### 0a. Output Language Constraint

Verification reports and branch-handling notes must use the language of the user request that triggered this workflow.

### 0b. Entry State Verification (Entry Check)

# Comet — OpenSpec + Superpowers 双星开发流程

OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。

```
OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
Superpowers 负责 HOW — 技术设计、计划、执行、收尾
```

**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**

<IMPORTANT>
本文中的“调用 `/comet-*`”“调用 OpenSpec/Superpowers 技能”均指使用当前平台的 Skill 工具加载对应 Skill，并把必要上下文作为 ARGUMENTS 传入。不得把“调用”降级为在当前 `/comet` 上下文中手工执行子 Skill 的步骤，也不得只按记忆或本文摘要模拟子 Skill。

# Comet 阶段 5：归档（Archive）

## 前置条件

- 验证已通过（阶段 4 完成）
- 分支已处理
- `openspec/changes/<name>/.comet.yaml` 中 `verify_result: pass`

## 步骤

### 0. 输出语言约束

归档摘要和生命周期闭环说明必须使用触发本次工作流的用户请求语言。

# Comet 阶段 3：计划与构建（Build）

## 前置条件

- Design Doc 已创建（阶段 2 完成）
- 活跃 change 存在

## 步骤

### 0. 入口状态验证（Entry Check）

按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：

```bash

# Comet 阶段 2：深度设计（Design）

## 前置条件

- 活跃 change 已存在（proposal.md、design.md、tasks.md）
- 无 Design Doc（`docs/superpowers/specs/` 下无对应文件）

> 职责边界：open 阶段的 `design.md` 给出**高层方案框架**（架构决策方向、方案选型、数据流）；design 阶段的 Design Doc 是对它的**深度技术细化**（详细实现设计、技术风险、测试策略、边界条件），是深化而非替代或重写。

## 步骤

### 0. 入口状态验证（Entry Check）

按 `comet/reference/scripts.md` 定位脚本（定位 `comet-env.mjs`），然后执行入口验证；从任意入口恢复时先按 `comet/reference/context-recovery.md` 运行恢复检查：

# Comet 预设路径：Hotfix

快速 bug fix 工作流：open → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。

**适用条件**（必须全部满足）：
1. 修复已有功能的 bug，不新增 capability
2. 不涉及接口变更或架构调整
3. 改动范围可预估（文件数仅作提示，不作为硬性升级条件，见下方升级判定）

**不适用**：如修复过程命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet` 流程。

---

## 流程（预设流程，6 步）

# Comet 阶段 1：开启（Open）

## 前置条件

- 无活跃 change，或用户希望创建新 change

## 步骤

### 0. 输出语言约束

传递给 OpenSpec 的所有提问和产物要求都必须包含输出语言约束：使用触发本次工作流的用户请求语言。恢复已有 change 且产物已有明确主语言时，除非用户明确要求切换，否则保持该语言。

### 1. 探索想法与需求澄清

# Comet 预设路径：Tweak

Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它串联 OpenSpec 的核心流程，复用 open、build、verify、archive 能力，仅跳过 Superpowers brainstorming 和完整 plan。

适用于串联 OpenSpec 的轻量改动，例如配置调整、文档或 prompt 优化，以及需 spec 驱动（含 delta spec）但不需要完整 `/comet` 深度设计流程的中等变更。delta spec 在 tweak 中是一等公民正常产物，需要 delta spec 本身不构成升级理由。

**适用条件**（必须全部满足）：
1. 可收敛为**单一 OpenSpec change**
2. 不需要 Superpowers Design Doc 和完整 plan 才能澄清方案
3. 不涉及跨模块、跨层级的架构协调
4. 任务规模可预估（文件数和任务数仅作提示，不作为硬性升级条件，见下方升级判定）

**不适用**：如变更过程中命中质变信号（见「升级判定」章节），由用户决定是否升级为完整 `/comet` 流程。

# Comet 阶段 4：验证与收尾（Verify）

## 前置条件

- 代码已提交（阶段 3 完成）
- tasks.md 全部任务已完成

## 步骤

### 0a. 输出语言约束

验证报告和分支处理说明必须使用触发本次工作流的用户请求语言。

### 0b. 入口状态验证（Entry Check）

Implement tasks from an OpenSpec change.

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **Select the change**

   If a name is provided, use it. Otherwise:
   - Infer from conversation context if the user mentioned a change
   - Auto-select if only one active change exists
   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select

   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).

Archive a completed change in the experimental workflow.

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **If no change name provided, prompt for selection**

   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.

   Show only active changes (not already archived).
   Include the schema used for each change if available.

   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.

Archive multiple completed changes in a single operation.

This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.

**Input**: None required (prompts for selection)

**Steps**

1. **Get active changes**

   Run `openspec list --json` to get all active changes.

   If no active changes exist, inform user and stop.

Continue working on a change by creating the next artifact.

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **If no change name provided, prompt for selection**

   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.

   Present the top 3-4 most recently modified changes as options, showing:
   - Change name
   - Schema (from `schema` field if present, otherwise "spec-driven")
   - Status (e.g., "0/5 tasks", "complete", "no tasks")

Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.

**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.

**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.

---

## The Stance

- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
- **Adaptive** - Follow interesting threads, pivot when new information emerges

Fast-forward through artifact creation - generate everything needed to start implementation in one go.

**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.

**Steps**

1. **If no clear input provided, ask what they want to build**

   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
   > "What change do you want to work on? Describe what you want to build or fix."

   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).

   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.

Start a new change using the experimental artifact-driven approach.

**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.

**Steps**

1. **If no clear input provided, ask what they want to build**

   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
   > "What change do you want to work on? Describe what you want to build or fix."

   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).

   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.

Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.

---

## Preflight

Before starting, check if the OpenSpec CLI is installed:

```bash
# Unix/macOS
openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
# Windows (PowerShell)
# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
```

Propose a new change - create the change and generate all artifacts in one step.

I'll create a change with artifacts:
- proposal.md (what & why)
- design.md (how)
- tasks.md (implementation steps)

When ready to implement, run /opsx:apply

---

**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.

**Steps**

Sync delta specs from a change to main specs.

This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **If no change name provided, prompt for selection**

   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.

   Show changes that have delta specs (under `specs/` directory).

Verify that an implementation matches the change artifacts (specs, tasks, design).

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **If no change name provided, prompt for selection**

   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.

   Show changes that have implementation tasks (tasks artifact exists).
   Include the schema used for each change if available.
   Mark changes with incomplete tasks as "(In Progress)".

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

# Dispatching Parallel Agents

## Overview

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.

## When to Use

```dot
digraph when_to_use {

# Executing Plans

## Overview

Load plan, review critically, execute all tasks, report when complete.

**Announce at start:** "I'm using the executing-plans skill to implement this plan."

**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (Claude Code, Codex CLI, Codex App, and Copilot CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.

## The Process

### Step 1: Load and Review Plan
1. Read plan file