7.8 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

name	description
comet-tweak	Comet 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → lightweight build → light verify → archive。适用于文案、配置、文档或 prompt 的局部优化。

Comet 预设路径：Tweak

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

适用于非 bug 的小范围变更，例如文案调整、配置调整、文档或 prompt 的局部优化。

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

不新增 capability
不改变架构
不涉及接口变化
通常不超过 3 个 tasks（文件数约束见下方升级条件）

不适用：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 /comet 流程。

流程（preset workflow，4 阶段）

0. 输出语言约束

精简版 OpenSpec 产物必须使用触发本次工作流的用户请求语言。

执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后进入归档前最终确认。

开始前先定位 Comet 脚本：

COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
if [ -z "$COMET_ENV" ]; then
  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
  return 1
fi
. "$COMET_ENV"

1. 快速开启（preset open）

复用 Comet open 能力创建 change，但使用 tweak 默认值：不执行 openspec-explore 长探索，直接进入精简 change 创建。

立即执行： 使用 Skill 工具加载 openspec-new-change 技能。禁止跳过此步骤。

技能加载后，按其指引创建精简版产物：

proposal.md — 变更动机 + 目标 + 范围
design.md — 简短实现说明（无需方案对比）
tasks.md — 不超过 3 个任务
无需 delta spec（除非变更改变了已有 spec 的验收场景；一旦需要 delta spec，升级为完整 /comet）

初始化 Comet 状态文件：

"$COMET_BASH" "$COMET_STATE" init <name> tweak

初始化后验证状态：

"$COMET_BASH" "$COMET_STATE" check <name> open

阶段守卫完成 open → build 过渡：

"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply

2. 轻量构建（preset build）

使用 tweak 默认值：build_mode: direct。跳过 Superpowers brainstorming 和 writing-plans。

继续或开始修改前，按 comet/reference/dirty-worktree.md 协议处理未提交改动。若归因后发现范围超出 tweak，按本文件“升级条件”处理。

立即执行： 按 tasks.md 逐个执行任务：

读取 openspec/changes/<name>/tasks.md，获取未完成任务列表
对每个未完成任务：
- 根据任务描述修改目标文件
- 运行项目格式化命令（如 mvn spotless:apply、npm run format 等）
- 运行相关测试确认通过
- 将 tasks.md 中对应 - [ ] 勾选为 - [x]
- 提交代码，commit message 格式：tweak: <简述变更>
全部任务完成后，显式运行项目相关测试和构建命令
运行阶段守卫完成 build → verify 过渡：

执行 tweak 期间，只要运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败，必须使用 Skill 工具加载 Superpowers systematic-debugging 技能。在完成根因调查前，不得提出或实施源码修复。

具体调查、最小失败测试、修复验证和保持当前 change 验证闭环的要求，按 comet/reference/debug-gate.md 执行。

"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply

状态文件自动更新为 phase: verify、verify_result: pending，然后进入验证。

3. 轻量验证（preset verify）

复用 /comet-verify。Tweak 必须保持轻量验证条件：≤ 3 tasks、≤ 4 files、无 delta spec、无新 capability。

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

如规模评估进入完整验证路径，停止 tweak，按升级条件阻塞确认处理。

验证通过后，按 /comet-verify 的规则将 .comet.yaml 的 verify_result 记录为 pass，归档前不得跳过该状态。验证通过后仍必须进入 /comet-archive 的归档前最终确认，不得自动运行归档脚本。

4. 归档（preset archive）

复用 /comet-archive。归档前必须满足 .comet.yaml 中 verify_result: pass，并等待 /comet-archive 的归档前最终确认。

立即执行： 使用 Skill 工具加载 comet-archive 技能进行归档。禁止跳过此步骤。

连续执行模式

Tweak 流程默认 **一次性连续执行**。调用 `/comet-tweak` 后agent 在 tweak 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：

遇到升级条件（见"升级条件"章节），必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认升级为完整流程
验证阶段（comet-verify）的验证失败决策和分支处理决策
归档前最终确认（comet-archive 执行归档脚本前）

执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成

每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。

升级条件

满足以下任一条件时，停止 tweak 流程，升级为完整 /comet：

条件	说明
改动涉及 5+ 文件	超出小改动范围
多模块协调修改	需要跨组件协调
需要新增测试用例 5+	变更复杂度上升
配置项新增或删除	非值修改的配置变更
需要新增 capability	超出局部优化
需要 delta spec	影响了已有规格

满足升级条件时必须按 comet/reference/decision-point.md 的协议暂停并等待用户明确确认升级为完整 /comet 流程。不得直接进入 /comet-design，不得自动补充 Design Doc。

用户确认升级后，必须先更新 workflow 和 phase 字段再进入完整流程：

"$COMET_BASH" "$COMET_STATE" set <name> workflow full
"$COMET_BASH" "$COMET_STATE" set <name> phase design

然后在当前 change 基础上补充 Design Doc：立即使用 Skill 工具加载 comet-design skill，后续正常走完整流程。若用户不确认升级，停止 tweak 并报告当前变更已超出 tweak 适用范围。

退出条件

小改动已完成，测试通过
change 已归档
未新增 capability、架构调整或接口变化
阶段守卫：build → verify 前运行 "$COMET_BASH" "$COMET_GUARD" <change-name> build --apply，verify → archive 前按 /comet-verify 规则运行 "$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply

自动衔接下一阶段

按 comet/reference/auto-transition.md 执行。关键命令：

"$COMET_BASH" "$COMET_STATE" next <name>

NEXT: auto → 调用 SKILL 指向的 skill 继续 tweak 流程（phase: build 返回 comet-tweak，verify 返回 comet-verify，archive 返回 comet-archive）
NEXT: manual → 不要调用下一 skill，按 HINT 提示用户手动运行 /<SKILL>
NEXT: done → 流程已完成，无需继续

7.8 KiB Raw Blame History Unescape Escape