Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
@rpamis/comet
Advanced tools
@rpamis/comet - npm Package Compare versions
@@ -31,2 +31,4 @@ --- | ||
| **幂等性**：build 阶段所有操作可安全重复执行。读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到第一个未勾选任务继续执行。已提交的任务不得重复提交。 | ||
| ### 1. 制定计划 | ||
@@ -92,3 +94,3 @@ | ||
| 这是用户决策点。必须暂停并等待用户明确选择隔离方式和执行方式，**不得根据推荐规则自行选择 `branch` 或 `worktree`**，也**不得根据推荐规则自行选择执行方式**。推荐规则只能用于说明建议，不能替代用户确认。 | ||
| 这是用户决策点。**必须使用 AskUserQuestion 工具暂停并等待用户明确选择隔离方式和执行方式**，不得根据推荐规则自行选择 `branch` 或 `worktree`，也不得根据推荐规则自行选择执行方式。推荐规则只能用于说明建议，不能替代用户确认。禁止仅输出文字提示后继续执行。 | ||
@@ -136,6 +138,6 @@ 用户选择后，更新 `isolation` 和 `build_mode` 字段： | ||
| | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 | | ||
| | 中 | 接口变更、新增组件、数据流变化 | 暂停并等待用户确认后，必须使用 Skill 工具加载 `superpowers:brainstorming` 更新 Design Doc + delta spec | | ||
| | 大 | 全新 capability 需求 | 必须暂停并等待用户确认拆分；用户确认后，通过 `/comet-open` 创建独立 change | | ||
| | 中 | 接口变更、新增组件、数据流变化 | **使用 AskUserQuestion 工具暂停并等待用户确认后**，必须使用 Skill 工具加载 `superpowers:brainstorming` 更新 Design Doc + delta spec | | ||
| | 大 | 全新 capability 需求 | **必须使用 AskUserQuestion 工具暂停并等待用户确认拆分**；用户确认后，通过 `/comet-open` 创建独立 change | | ||
| **50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，必须暂停并等待用户决定是否拆分为新 change。 | ||
| **50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，**必须使用 AskUserQuestion 工具暂停并等待用户决定是否拆分为新 change**。 | ||
@@ -155,3 +157,3 @@ 创建独立 change 时必须调用 `/comet-open`，不得直接调用 `/opsx:new`。`/comet-open` 会同时创建 OpenSpec 产物和 `.comet.yaml`，避免新 change 脱离 Comet 状态机。 | ||
| - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化 | ||
| - **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行 | ||
| - **上下文压缩后恢复**：先运行 `bash "$COMET_STATE" check <change-name> build --recover`，脚本输出结构化恢复上下文（isolation/build_mode 状态、plan 路径、任务完成进度、恢复动作）。根据 Recovery action 决定下一步。 | ||
| - **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理： | ||
@@ -190,4 +192,4 @@ 1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 4「Spec 增量更新」分级处理 | ||
| 退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段： | ||
| 退出条件满足后（包括用户选择工作方式），自动流转到下一阶段： | ||
| > **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。 |
@@ -31,2 +31,4 @@ --- | ||
| **幂等性**：所有 design 阶段操作可以安全重试。如果 `handoff_context` 和 `handoff_hash` 已存在，先确认它们与当前产物一致再决定是否重新生成。 | ||
| ### 1a. 生成 OpenSpec → Superpowers 交接包 | ||
@@ -107,3 +109,3 @@ | ||
| brainstorming 产出设计方案后，**必须暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。 | ||
| brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。也不得仅输出文字提示后继续执行。 | ||
@@ -152,6 +154,16 @@ 暂停时只展示必要摘要： | ||
| ## 上下文压缩恢复 | ||
| design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行： | ||
| ```bash | ||
| bash "$COMET_STATE" check <change-name> design --recover | ||
| ``` | ||
| 脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。 | ||
| ## 自动流转 | ||
| 退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段： | ||
| 退出条件满足后（包括用户确认设计方案），自动流转到下一阶段： | ||
| > **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。 |
@@ -129,3 +129,3 @@ --- | ||
| 1. 遇到升级条件（见"升级条件"章节） | ||
| 1. 遇到升级条件（见"升级条件"章节），**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整流程 | ||
| 2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择 | ||
@@ -153,3 +153,3 @@ 3. 验证阶段（comet-verify）的验证失败决策和分支处理决策 | ||
| 满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。 | ||
| 满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。 | ||
@@ -156,0 +156,0 @@ 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程： |
@@ -24,2 +24,4 @@ --- | ||
| **命名与范围守卫**：change name 必须使用用户指定或通过 AskUserQuestion 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。 | ||
| 确认以下产物已创建： | ||
@@ -64,2 +66,4 @@ | ||
| **幂等性**：open 阶段所有操作可安全重复执行。如 `.comet.yaml` 已处于 `phase: open` 且三个产物文件均已存在，跳过已完成步骤，从第一个缺失步骤继续。 | ||
| ### 4. 内容完整性检查 | ||
@@ -72,5 +76,25 @@ | ||
| **文件存在性验证**：逐个确认三个文件路径存在且非空。任一文件缺失或为空时，不得进入 Step 5 或执行阶段守卫，必须回到创建步骤补充。 | ||
| ### 5. 用户审视确认（阻塞点） | ||
| 三个文档创建完成且内容完整性检查通过后，**必须使用 AskUserQuestion 工具暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。 | ||
| AskUserQuestion 必须以单选题形式呈现，包含以下摘要和选项： | ||
| **摘要内容**： | ||
| - **proposal.md**：问题背景、目标、范围 | ||
| - **design.md**：高层架构决策、方案选型 | ||
| - **tasks.md**：任务数量和关键任务描述 | ||
| **选项**： | ||
| - 「确认，继续下一阶段」— 产物符合预期，执行阶段守卫流转 | ||
| - 「需要调整」— 附带调整说明，修改后重新请求确认 | ||
| 用户选择「确认」后继续执行退出条件。用户选择「需要调整」时，按其说明修改对应文件，然后重新使用 AskUserQuestion 请求确认。 | ||
| ## 退出条件 | ||
| - proposal.md、design.md、tasks.md 均已创建且内容完整 | ||
| - **用户已确认** proposal、design、tasks 内容符合预期 | ||
| - **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段 | ||
@@ -88,3 +112,3 @@ | ||
| 退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段： | ||
| 用户确认后，退出条件满足，自动流转到下一阶段： | ||
@@ -91,0 +115,0 @@ > **REQUIRED NEXT SKILL（完整流程）:** 调用 `comet-design` skill 进入深度设计阶段。 |
@@ -114,3 +114,3 @@ --- | ||
| 1. 遇到升级条件（见"升级条件"章节） | ||
| 1. 遇到升级条件（见"升级条件"章节），**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整流程 | ||
| 2. 验证阶段（comet-verify）的验证失败决策和分支处理决策 | ||
@@ -138,3 +138,3 @@ | ||
| 满足升级条件时必须暂停并等待用户明确确认升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。 | ||
| 满足升级条件时**必须使用 AskUserQuestion 工具暂停并等待用户明确确认**升级为完整 `/comet` 流程。不得直接进入 `/comet-design`，不得自动补充 Design Doc。不得仅输出文字提示后继续执行。 | ||
@@ -141,0 +141,0 @@ 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程： |
@@ -31,2 +31,4 @@ --- | ||
| **幂等性**：verify 阶段所有检查可安全重复执行。如 `verify_result` 已为 `pass` 且 `branch_status` 已为 `handled`，说明验证已完成，直接执行 guard 流转。如 `verify_result` 为 `pending`，从头开始验证。 | ||
| ### 1. 改动规模评估 | ||
@@ -71,3 +73,3 @@ | ||
| 验证不通过时必须暂停并等待用户决定修复或接受偏差。不得自动运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。 | ||
| 验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。禁止仅输出文字提示后继续执行。 | ||
@@ -79,2 +81,4 @@ 暂停时必须列出： | ||
| **不确定性原则**：无法确定严重程度时，降级处理（SUGGESTION > WARNING > CRITICAL）。仅对构建失败、测试失败、安全问题使用 CRITICAL；模糊或不确定的问题标为 WARNING 或 SUGGESTION。 | ||
| 用户选择后按以下方式继续： | ||
@@ -134,3 +138,3 @@ - **全部修复**：运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复 | ||
| **Spec 漂移处理**（用户决策点）： | ||
| - 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须暂停并等待用户选择处理方式**，不得自动选择。选项： | ||
| - 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须使用 AskUserQuestion 工具以单选题形式暂停并等待用户选择处理方式**，不得自动选择。选项： | ||
| - 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物；写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策 | ||
@@ -152,3 +156,3 @@ - 选项 B：用户选择 B 后，运行 `bash "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 `superpowers:brainstorming` 更新 Design Doc + delta spec | ||
| 这是用户决策点。**必须暂停并等待用户选择分支处理方式**，不得根据推荐、默认值或当前分支状态自行选择。只有在用户完成选择且对应操作完成后，才允许写入 `branch_status: handled`。 | ||
| 这是用户决策点。**必须使用 AskUserQuestion 工具暂停并等待用户选择分支处理方式**，不得根据推荐、默认值或当前分支状态自行选择。禁止仅输出文字提示后继续执行。只有在用户完成选择且对应操作完成后，才允许写入 `branch_status: handled`。 | ||
@@ -188,6 +192,16 @@ **确认项**： | ||
| ## 上下文压缩恢复 | ||
| Verify 阶段可能触发上下文压缩。恢复时先运行： | ||
| ```bash | ||
| bash "$COMET_STATE" check <change-name> verify --recover | ||
| ``` | ||
| 脚本输出结构化恢复上下文（phase、验证状态、分支状态、恢复动作），根据输出的 Recovery action 决定下一步。 | ||
| ## 自动流转 | ||
| 退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段： | ||
| 退出条件满足后（包括用户选择分支处理方式），自动流转到下一阶段： | ||
| > **REQUIRED NEXT SKILL:** 调用 `comet-archive` skill 进入归档阶段。 |
@@ -106,15 +106,26 @@ --- | ||
| **连续执行要求**：从检测到的阶段开始，agent 必须自动推进后续阶段；自动推进只适用于没有用户决策的衔接点。遇到用户决策点时必须暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认。 | ||
| **连续执行要求**：从检测到的阶段开始，agent 自动推进后续阶段。但**自动推进仅适用于没有用户决策的衔接点**。遇到用户决策点时，**必须使用 AskUserQuestion 工具暂停并等待用户明确回复**，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。 | ||
| **决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。 | ||
| **决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住，**使用 AskUserQuestion 工具等待用户选择**。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。 | ||
| 需要用户参与的节点（仅在这些节点暂停）： | ||
| 1. brainstorming 确认设计方案 | ||
| 2. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成） | ||
| 3. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择） | ||
| 4. finishing-branch 选择分支处理方式 | ||
| 5. 遇到升级条件（hotfix/tweak → 完整流程） | ||
| 6. build 阶段范围扩张需重新设计或拆分新 change | ||
| 1. open 阶段 proposal/design/tasks 审视确认 | ||
| 2. brainstorming 确认设计方案 | ||
| 3. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成） | ||
| 4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择） | ||
| 5. finishing-branch 选择分支处理方式 | ||
| 6. 遇到升级条件（hotfix/tweak → 完整流程） | ||
| 7. build 阶段范围扩张需重新设计或拆分新 change | ||
| agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。 | ||
| agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止以文字输出代替工具等待——必须通过 AskUserQuestion 明确获取用户选择后才能继续**。 | ||
| **红旗清单** — 以下想法出现时立即停止并检查： | ||
| | Agent 心理 | 实际风险 | | ||
| |-----------|---------| | ||
| | "用户应该会同意这个方案" | 不能替用户决策，用 AskUserQuestion | | ||
| | "这只是个小改动，不需要确认" | 决策点无大小之分，阻塞点必须等待 | | ||
| | "用户之前选过 A，这次也选 A" | 历史偏好不能替代当前确认 | | ||
| | "我已经解释了方案，用户没反对" | 没反对 ≠ 同意，必须用工具获取明确选择 | | ||
| | "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result | | ||
| </IMPORTANT> | ||
@@ -121,0 +132,0 @@ |
@@ -31,2 +31,4 @@ --- | ||
| **Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` field to confirm still in build, read plan header `base-ref`, then read tasks.md to find the first unchecked task. Already-committed tasks must not be re-committed. | ||
| ### 1. Create Plan | ||
@@ -92,3 +94,3 @@ | ||
| This is a user decision point. Must pause and wait for the user to explicitly choose both isolation method and execution method. You **must not choose `branch` or `worktree` based on recommendation rules**, and **must not choose the execution method based on recommendation rules**. Recommendation rules are for suggestion only, not a substitute for user confirmation. | ||
| This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for the user to explicitly choose both isolation method and execution method**. Must not choose `branch` or `worktree` based on recommendation rules, and must not choose the execution method based on recommendation rules. Recommendation rules are for suggestion only, not a substitute for user confirmation. Must not just output a text prompt and then continue executing. | ||
@@ -136,6 +138,6 @@ After user selection, update `isolation` and `build_mode` fields: | ||
| | Small | Missing acceptance scenarios, edge cases | Directly edit delta spec + design.md, append tasks.md tasks | | ||
| | Medium | Interface changes, new components, data flow changes | Pause and wait for user confirmation, then must use Skill tool to load `superpowers:brainstorming` to update Design Doc + delta spec | | ||
| | Large | Brand-new capability requirements | Must pause and wait for user confirmation to split; after user confirms, create independent change through `/comet-open` | | ||
| | Medium | Interface changes, new components, data flow changes | **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm**, then must use Skill tool to load `superpowers:brainstorming` to update Design Doc + delta spec | | ||
| | Large | Brand-new capability requirements | **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm the split**; after user confirms, create independent change through `/comet-open` | | ||
| **50% Threshold Determination**: Using initial task count in tasks.md as baseline, if new tasks exceed half of that total, it's considered outside original plan scope, must pause and wait for the user to decide whether to split into new change. | ||
| **50% Threshold Determination**: Using initial task count in tasks.md as baseline, if new tasks exceed half of that total, it's considered outside original plan scope, **must use the AskUserQuestion tool to pause and wait for the user to decide whether to split into a new change**. Must not just output a text prompt and then continue executing. | ||
@@ -155,3 +157,3 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new` directly. `/comet-open` creates both OpenSpec artifacts and `.comet.yaml`, preventing the new change from leaving the Comet state machine. | ||
| - **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable | ||
| - **After context compaction**: read `.comet.yaml` to confirm the phase is still build, read the plan header `base-ref`, then read tasks.md to find the next unchecked task | ||
| - **After context compaction**: first run `bash "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step. | ||
| - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling: | ||
@@ -190,4 +192,4 @@ 1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates" | ||
| After exit conditions are met, **proceed immediately to the next phase without waiting for user input**: | ||
| After exit conditions are met (including user selecting workflow configuration), auto-transition to next phase: | ||
| > **REQUIRED NEXT SKILL:** Invoke `comet-verify` skill to enter the verification and completion phase. |
@@ -31,2 +31,4 @@ --- | ||
| **Idempotency**: All design phase operations can be safely re-executed. If `handoff_context` and `handoff_hash` already exist, confirm they match current artifacts before deciding whether to regenerate. | ||
| ### 1a. Generate OpenSpec → Superpowers Handoff Package | ||
@@ -107,3 +109,3 @@ | ||
| After brainstorming produces a design proposal, **must pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation. | ||
| After brainstorming produces a design proposal, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation. Must not just output a text prompt and then continue executing. | ||
@@ -152,6 +154,16 @@ When pausing, only present essential summary: | ||
| ## Context Compaction Recovery | ||
| The design phase may trigger context compaction during brainstorming. To recover, first run: | ||
| ```bash | ||
| bash "$COMET_STATE" check <change-name> design --recover | ||
| ``` | ||
| The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the Recovery action to determine next step. | ||
| ## Automatic Transition | ||
| After exit conditions are met, **proceed immediately to the next phase without waiting for user input**: | ||
| After exit conditions are met (including user confirming the design proposal), auto-transition to next phase: | ||
| > **REQUIRED NEXT SKILL:** Invoke `comet-build` skill to enter the plan and build phase. |
@@ -129,3 +129,3 @@ --- | ||
| 1. Encountering upgrade conditions (see "Upgrade Conditions" section). Handle through the upgrade-condition blocking confirmation | ||
| 1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow | ||
| 2. workspace isolation and execution-method selection when tasks exceed 3 and transfer to `/comet-build` | ||
@@ -153,3 +153,3 @@ 3. verify phase (comet-verify) verification-failure and branch-handling decisions | ||
| When upgrade conditions are met, must pause and wait for the user to explicitly confirm upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. | ||
| When upgrade conditions are met, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. Must not just output a text prompt and then continue executing. | ||
@@ -156,0 +156,0 @@ After user confirms upgrade, **must first update the workflow field** before entering full flow: |
@@ -24,2 +24,4 @@ --- | ||
| **Naming and scope guard**: Change name must use a user-specified or AskUserQuestion-confirmed name — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently. | ||
| Confirm the following artifacts have been created: | ||
@@ -64,2 +66,4 @@ | ||
| **Idempotency**: All open phase operations can be safely re-executed. If `.comet.yaml` is already at `phase: open` and all three artifact files exist, skip completed steps and continue from the first missing step. | ||
| ### 4. Content Completeness Check | ||
@@ -72,5 +76,25 @@ | ||
| **File existence verification**: Confirm all three file paths exist and are non-empty. If any file is missing or empty, must not enter Step 5 or execute phase guard — return to creation step to fill the gap. | ||
| ### 5. User Review and Confirmation (Blocking Point) | ||
| After the three documents are created and content completeness check passes, **must use the AskUserQuestion tool to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation. | ||
| AskUserQuestion must be presented as a single-select question with the following summary and options: | ||
| **Summary content**: | ||
| - **proposal.md**: problem background, goals, scope | ||
| - **design.md**: high-level architecture decisions, approach selection | ||
| - **tasks.md**: task count and key task descriptions | ||
| **Options**: | ||
| - "Confirm, proceed to next phase" — artifacts meet expectations, execute phase guard transition | ||
| - "Needs adjustment" — include adjustment notes, modify and re-request confirmation | ||
| After user selects "Confirm", proceed to exit conditions. When user selects "Needs adjustment", modify the corresponding files per their notes, then re-use AskUserQuestion to request confirmation. | ||
| ## Exit Conditions | ||
| - proposal.md, design.md, tasks.md all created with complete content | ||
| - **User has confirmed** proposal, design, tasks content meets expectations | ||
| - **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase | ||
@@ -88,3 +112,3 @@ | ||
| After exit conditions are met, **proceed immediately to the next phase without waiting for user input**: | ||
| After user confirmation and exit conditions are met, auto-transition to next phase: | ||
@@ -91,0 +115,0 @@ > **REQUIRED NEXT SKILL (full workflow):** Invoke `comet-design` skill to enter the deep design phase. |
@@ -114,3 +114,3 @@ --- | ||
| 1. Encountering upgrade conditions (see "Upgrade Conditions" section). Handle through the upgrade-condition blocking confirmation | ||
| 1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow | ||
| 2. verify phase (comet-verify) verification-failure and branch-handling decisions | ||
@@ -138,3 +138,3 @@ | ||
| When upgrade conditions are met, must pause and wait for the user to explicitly confirm upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. | ||
| When upgrade conditions are met, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. Must not just output a text prompt and then continue executing. | ||
@@ -141,0 +141,0 @@ After user confirms upgrade, **must first update the workflow field** before entering full flow: |
@@ -31,2 +31,4 @@ --- | ||
| **Idempotency**: All verify phase checks can be safely re-executed. If `verify_result` is already `pass` and `branch_status` is `handled`, verification is complete — execute guard to transition. If `verify_result` is `pending`, start verification from the beginning. | ||
| ### 1. Scale Assessment | ||
@@ -71,3 +73,3 @@ | ||
| When verification does not pass, must pause and wait for the user to decide fix or accept deviation. Must not automatically run `bash "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. | ||
| When verification does not pass, **must use the AskUserQuestion tool to pause and wait for the user to decide fix or accept deviation**. Must not automatically run `bash "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. Must not just output a text prompt and then continue executing. | ||
@@ -79,2 +81,4 @@ When pausing, must list: | ||
| **Uncertainty principle**: When severity is unclear, downgrade (SUGGESTION > WARNING > CRITICAL). Only use CRITICAL for build failures, test failures, and security issues; ambiguous or uncertain issues should be WARNING or SUGGESTION. | ||
| After user selection, continue as follows: | ||
@@ -134,3 +138,3 @@ - **Fix all**: Run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix | ||
| **Spec Drift Handling** (user decision point): | ||
| - If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must pause and wait for user to choose handling method**; must not select automatically. Options: | ||
| - If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the AskUserQuestion tool as a single-select question to pause and wait for user to choose handling method**; must not select automatically. Options: | ||
| - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change | ||
@@ -152,3 +156,3 @@ - Option B: After user selects B, run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load `superpowers:brainstorming` to update Design Doc + delta spec | ||
| This is a user decision point. **Must pause and wait for user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written. | ||
| This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Must not just output a text prompt and then continue executing. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written. | ||
@@ -190,4 +194,14 @@ **Confirmation items**: | ||
| After exit conditions are met, **proceed immediately to the next phase without waiting for user input**: | ||
| After exit conditions are met (including user selecting branch handling method), auto-transition to next phase: | ||
| > **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archive phase. | ||
| ## Context Compaction Recovery | ||
| The verify phase may trigger context compaction. To recover, first run: | ||
| ```bash | ||
| bash "$COMET_STATE" check <change-name> verify --recover | ||
| ``` | ||
| The script outputs structured recovery context (phase, verification status, branch status, recovery action). Follow the Recovery action to determine next step. |
@@ -11,2 +11,3 @@ #!/bin/bash | ||
| # check <change-name> <phase> — Verify entry requirements for a phase | ||
| # check <change-name> <phase> --recover — Output structured recovery context for compaction resume | ||
| # scale <change-name> — Assess and set verification mode based on metrics | ||
@@ -593,2 +594,165 @@ # | ||
| # --- Recovery context for compaction resume --- | ||
| field_status() { | ||
| # Args: field_name value [file_path] | ||
| # Prints: "field_name: DONE (value)" or "field_name: PENDING" | ||
| local field="$1" | ||
| local value="$2" | ||
| local file_path="${3:-}" | ||
| if [ -z "$value" ] || [ "$value" = "null" ]; then | ||
| echo " - ${field}: PENDING" | ||
| elif [ -n "$file_path" ] && [ ! -f "$file_path" ]; then | ||
| echo " - ${field}: BROKEN (path ${value} does not exist)" | ||
| else | ||
| echo " - ${field}: DONE (${value})" | ||
| fi | ||
| } | ||
| cmd_recover() { | ||
| local change_name="$1" | ||
| validate_change_name "$change_name" | ||
| local change_dir="openspec/changes/$change_name" | ||
| local yaml_file="$change_dir/.comet.yaml" | ||
| if [ ! -f "$yaml_file" ]; then | ||
| red "ERROR: .comet.yaml not found at $yaml_file" | ||
| exit 1 | ||
| fi | ||
| local phase workflow | ||
| phase=$(cmd_get "$change_name" "phase") | ||
| workflow=$(cmd_get "$change_name" "workflow") | ||
| echo "=== Recovery Context: ${change_name} ===" | ||
| echo "Phase: ${phase}" | ||
| echo "Workflow: ${workflow}" | ||
| echo "" | ||
| # Read all relevant fields | ||
| local design_doc plan verify_result verify_mode verification_report | ||
| local branch_status handoff_context handoff_hash isolation build_mode direct_override | ||
| design_doc=$(cmd_get "$change_name" "design_doc") | ||
| plan=$(cmd_get "$change_name" "plan") | ||
| verify_result=$(cmd_get "$change_name" "verify_result") | ||
| verify_mode=$(cmd_get "$change_name" "verify_mode") | ||
| verification_report=$(cmd_get "$change_name" "verification_report") | ||
| branch_status=$(cmd_get "$change_name" "branch_status") | ||
| handoff_context=$(cmd_get "$change_name" "handoff_context") | ||
| handoff_hash=$(cmd_get "$change_name" "handoff_hash") | ||
| isolation=$(cmd_get "$change_name" "isolation") | ||
| build_mode=$(cmd_get "$change_name" "build_mode") | ||
| direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true) | ||
| echo "State fields:" | ||
| # Phase-specific field reporting | ||
| case "$phase" in | ||
| open) | ||
| echo " Artifacts:" | ||
| for f in proposal.md design.md tasks.md; do | ||
| if file_nonempty "$change_dir/$f"; then | ||
| echo " - ${f}: DONE" | ||
| else | ||
| echo " - ${f}: PENDING" | ||
| fi | ||
| done | ||
| echo "" | ||
| echo "Recovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation." | ||
| ;; | ||
| design) | ||
| echo " Artifacts:" | ||
| for f in proposal.md design.md tasks.md; do | ||
| if file_nonempty "$change_dir/$f"; then | ||
| echo " - ${f}: DONE" | ||
| else | ||
| echo " - ${f}: MISSING (unexpected in design phase)" | ||
| fi | ||
| done | ||
| echo "" | ||
| echo " Design progress:" | ||
| field_status "handoff_context" "$handoff_context" "$handoff_context" | ||
| field_status "handoff_hash" "$handoff_hash" | ||
| field_status "design_doc" "$design_doc" "$design_doc" | ||
| echo "" | ||
| if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then | ||
| echo "Recovery action: Design Doc already created and linked. Run guard to transition to build." | ||
| elif [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ] && [ -f "$handoff_context" ]; then | ||
| echo "Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c)." | ||
| else | ||
| echo "Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package)." | ||
| fi | ||
| ;; | ||
| build) | ||
| echo " Build decisions:" | ||
| field_status "isolation" "$isolation" | ||
| field_status "build_mode" "$build_mode" | ||
| if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ]; then | ||
| field_status "direct_override" "$direct_override" | ||
| fi | ||
| echo "" | ||
| echo " Plan:" | ||
| field_status "plan" "$plan" "$plan" | ||
| echo "" | ||
| # Count completed vs pending tasks | ||
| local tasks_file="$change_dir/tasks.md" | ||
| local total=0 done=0 pending=0 | ||
| if [ -f "$tasks_file" ]; then | ||
| total=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo "0") | ||
| done=$(grep -c '^\- \[x\]' "$tasks_file" 2>/dev/null || echo "0") | ||
| pending=$((total - done)) | ||
| echo " Tasks: ${done}/${total} done, ${pending} pending" | ||
| else | ||
| echo " Tasks: tasks.md MISSING" | ||
| fi | ||
| echo "" | ||
| if [ "$isolation" = "null" ] || [ -z "$isolation" ]; then | ||
| echo "Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice." | ||
| elif [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; then | ||
| echo "Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method." | ||
| elif [ ! -f "$tasks_file" ]; then | ||
| echo "Recovery action: tasks.md missing. Verify change directory integrity." | ||
| elif [ "$pending" -gt 0 ]; then | ||
| echo "Recovery action: Read tasks.md and continue from first unchecked task." | ||
| else | ||
| echo "Recovery action: All tasks done. Run guard to transition to verify." | ||
| fi | ||
| ;; | ||
| verify) | ||
| echo " Verification:" | ||
| field_status "verify_result" "$verify_result" | ||
| field_status "verify_mode" "$verify_mode" | ||
| field_status "verification_report" "$verification_report" "$verification_report" | ||
| field_status "branch_status" "$branch_status" | ||
| echo "" | ||
| if [ "$verify_result" = "pass" ] && [ "$branch_status" = "handled" ]; then | ||
| echo "Recovery action: Verification complete. Run guard to transition to archive." | ||
| elif [ "$verify_result" = "pass" ]; then | ||
| echo "Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled." | ||
| elif [ "$verify_result" = "fail" ]; then | ||
| echo "Recovery action: Verification failed and rolled back to build. Resume from /comet-build." | ||
| else | ||
| echo "Recovery action: Verification not yet started or in progress. Run scale assessment then verify." | ||
| fi | ||
| ;; | ||
| archive) | ||
| echo " Archive:" | ||
| field_status "verify_result" "$verify_result" | ||
| field_status "archived" "$(cmd_get "$change_name" "archived")" | ||
| echo "" | ||
| echo "Recovery action: Run /comet-archive to complete archiving." | ||
| ;; | ||
| *) | ||
| red "ERROR: Unknown phase: $phase" | ||
| exit 1 | ||
| ;; | ||
| esac | ||
| echo "" | ||
| echo "=== End Recovery Context ===" | ||
| } | ||
| cmd_scale() { | ||
@@ -699,7 +863,12 @@ local change_name="$1" | ||
| if [ $# -lt 2 ]; then | ||
| red "Usage: comet-state.sh check <change-name> <phase>" >&2 | ||
| red "Usage: comet-state.sh check <change-name> <phase> [--recover]" >&2 | ||
| red "Phases: open, design, build, verify, archive" >&2 | ||
| exit 1 | ||
| fi | ||
| cmd_check "$@" | ||
| # Detect --recover flag (3rd argument) | ||
| if [ "${3:-}" = "--recover" ]; then | ||
| cmd_recover "$1" | ||
| else | ||
| cmd_check "$@" | ||
| fi | ||
| ;; | ||
@@ -706,0 +875,0 @@ scale) |
@@ -106,15 +106,26 @@ --- | ||
| **Continuous execution requirement**: starting from the detected phase, the agent must automatically continue through all later phases. Auto-advancing only applies at transition points without user decisions. When encountering user decision points, must pause and wait for the user's explicit response. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation. | ||
| **Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the AskUserQuestion tool to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing. | ||
| **Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes. | ||
| **Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop, **using the AskUserQuestion tool to wait for the user's choice**. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes. | ||
| Nodes requiring user participation (pause only at these nodes): | ||
| 1. Confirm design approach during brainstorming | ||
| 2. Select workflow configuration during build phase (isolation + execution method, single interaction) | ||
| 3. Decide to fix or accept deviation when verify fails (including Spec drift handling) | ||
| 4. Choose branch handling method for finishing-branch | ||
| 5. Encounter upgrade conditions (hotfix/tweak → full workflow) | ||
| 6. Build phase scope expansion requiring redesign or new change split | ||
| 1. Open phase proposal/design/tasks review and confirmation | ||
| 2. Confirm design approach during brainstorming | ||
| 3. Select workflow configuration during build phase (isolation + execution method, single interaction) | ||
| 4. Decide to fix or accept deviation when verify fails (including Spec drift handling) | ||
| 5. Choose branch handling method for finishing-branch | ||
| 6. Encounter upgrade conditions (hotfix/tweak → full workflow) | ||
| 7. Build phase scope expansion requiring redesign or new change split | ||
| Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. | ||
| Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **text output must NOT substitute for tool-based waiting — must explicitly obtain the user's choice via AskUserQuestion before continuing**. | ||
| **Red Flags** — when these thoughts appear, STOP and check: | ||
| | Agent Thought | Actual Risk | | ||
| |--------------|-------------| | ||
| | "The user would probably agree with this approach" | Cannot decide for the user — use AskUserQuestion | | ||
| | "This is a small change, confirmation isn't needed" | Decision points have no size exception — blocking points must wait | | ||
| | "The user chose A last time, so A again" | Historical preference cannot substitute for current confirmation | | ||
| | "I explained the plan and the user didn't object" | No objection ≠ consent — must use tool to get explicit choice | | ||
| | "The flow has reached this point, should be fine" | Verification not passed ≠ passed — check verify_result | | ||
| </IMPORTANT> | ||
@@ -121,0 +132,0 @@ |
+1
-1
| { | ||
| "name": "@rpamis/comet", | ||
| "version": "0.3.4", | ||
| "version": "0.3.5", | ||
| "description": "OpenSpec + Superpowers dual-star development workflow", | ||
@@ -5,0 +5,0 @@ "keywords": [ |
No alert changes
Improved metrics
- Total package byte prevSize
373099
4.78%No dependency changes