open → build → verify → archive 四步,跳过 brainstorming 和完整 plan,但把 delta spec 当作一等产物——并通过 OpenSpec 原生的 apply action 构建。

tweak 不是随手小改;它用 delta spec 和 OpenSpec apply 承接可收敛的中等调整
不少用户反馈 full 流程对配置调整、文档优化、行为微调这类变更太重。tweak 就是为这类场景设计的:保留 OpenSpec 的 spec 生命周期和归档,去掉前期深度设计成本。怎么触发
tweak 通常不是你手敲的命令。用户调用/comet 并进入 Classic 后,内部 /comet-classic 会在 Step 0 优先做预设检测:
你也可以直接输入
/comet-tweak。正常恢复仍使用 /comet;配置进入 Classic 后,内部 /comet-classic 会读取 .comet.yaml 的 workflow 字段,并在 phase: build 时路由回 /comet-tweak。
适合什么场景
适用条件(必须全部满足):- 可收敛为单一 OpenSpec change
- 不需要 Superpowers Design Doc 和完整 plan 才能澄清方案
- 不涉及跨模块、跨层级的架构协调
- 任务规模可预估(文件数和任务数仅作提示,不是硬性升级条件)
和 full、hotfix 的关系
关键区别是 delta spec 的地位:hotfix 把 delta spec 当例外,tweak 把它当正常产物——
需要 delta spec 本身不构成升级理由。如果你的变更天然需要修改 spec,tweak
是正确选择。另一个关键区别是 build 方式:tweak 用 OpenSpec 原生 apply 路径(只属于 tweak,full
不得套用)。
你会经历什么
Step 1:快速开启(预设 open)
加载openspec-new-change(不做 openspec-explore 长探索),创建精简版产物:
初始化 tweak 状态:
design.md(只对 full 要求),所以 open 完成后直接跳到 build,跳过 design 阶段。init 写入和 hotfix 相同的轻量执行默认值(build_mode: direct、tdd_mode: direct、review_mode: off、verify_mode: light),但 isolation 保持 null,入口会让你显式选择当前分支、创建分支或创建 worktree。确认后记录 isolation 和 bound_branch,后续意外切换分支会被阻止。详见 hotfix 预设 · 初始化的默认值。
Step 2:OpenSpec apply 构建(tweak 专属 build)
这是 tweak 和 hotfix 最大的区别。 tweak 不用手动跑 tasks 循环,而是用 OpenSpec 原生的openspec-apply-change 执行任务:
使用默认值 build_mode: direct,跳过 Superpowers brainstorming 和 writing-plans。apply 流程:
- 运行
openspec status --change "<name>" --json,确认 schema 和任务 artifact - 运行
openspec instructions apply --change "<name>" --json,读取 apply 指令、contextFiles、任务进度和动态 instruction - 读取 apply 指令列出的所有 context files(不得只凭旧对话或手写 tasks 循环实现)
- 按 apply 指令逐个完成未勾选任务,保持改动最小且聚焦
- 每完成一个任务后:格式化 → 跑相关测试 → 按
openspec-apply-change规则勾选 → 提交(tweak: <简述变更>) - 全部任务完成后,显式运行项目相关测试和构建命令
- 运行 build guard 完成 build→verify 过渡
systematic-debugging(共享的异常调试协议)。build 全程持续判断升级信号,并在 build→verify guard 前做集中复核。
Step 3:验证(预设 verify,按 delta spec 分流)
复用/comet-verify,验证路径取决于是否有 delta spec:
有 delta spec 时显式设置:
Step 4:归档(预设 archive)
复用/comet-archive。要求 verify_result: pass,等待归档前最终确认。如有 delta spec,按 ADDED/MODIFIED/REMOVED/RENAMED 语义同步到 main spec。
升级判定(三层分工)
和 hotfix 一样的三层分工,但文件数 tripwire 阈值更高(超过 6 个文件,因为 tweak 本身可能触及更多文件):1. 质变信号(命中任一即暂停)
注意 tweak 的第二个信号是「需要拆分为多个 OpenSpec changes」,而 hotfix 是「需要新增
capability」——这反映了两者适用条件的差异(tweak 要求单一 change)。
2. 文件数 tripwire(用户拍板)
改动文件数超过 6 个时暂停交你决定。文件数是提示触发器,不是硬性升级条件——文件多不等于有质变。3. 验证级别(scale 脚本判定)
comet-state scale 只决定 verify_mode,不卡流程、不触发升级。
升级决策(停顿点)
命中信号或 tripwire 时,Comet 暂停让你二选一(不能自行升级或自行判定可继续):
选 B 后用合法升级通道(不能手工编辑
.comet.yaml):
workflow: full、classic_profile: full、phase 回退到 design、清空 design_doc,然后加载 /comet-design 补 Design Doc。已完成的代码、tasks 和 OpenSpec artifacts 都保留——你只补一个 Design Doc。preset-escalate 只能从 phase: build 的 hotfix/tweak 触发。
连续执行和必停点
tweak 默认一次性连续执行——调用后自动推进,不主动停顿。但无论auto_transition 取何值,以下情况必须暂停等你确认:
- 命中升级判定信号
- 验证阶段的验证失败决策,以及 Archive 阶段的归档与交付确认
- 归档前最终确认
auto_transition: false 时降级为逐阶段手动推进。
退出条件
- 变更已完成,测试通过
- change 已归档
- 如有 spec 变更,已同步到 main spec
- 阶段守卫:build→verify 前
comet-guard <name> build --apply,verify→archive 前comet-guard <name> verify --apply
恢复
tweak 幂等。中断后用/comet 恢复;配置进入 Classic 后,内部 /comet-classic 读取 .comet.yaml 的 workflow 字段,并在 phase: build 时路由回 /comet-tweak。comet-state check <name> build --recover 给出恢复上下文,从 tasks.md 第一个未勾选任务继续。
下一步
- hotfix 预设 — 另一个轻量预设(修 bug)
- 自动推进机制 — 预设的连续执行、升级和
preset-escalate - 五阶段停顿点和用户选择点 — tweak 的停顿点
- verify 阶段 — tweak 复用的验证流程

