comet-tweak

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comet 预设路径：Tweak

Comet Preset Path: Tweak

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

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

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

不新增 capability
不改变架构
不涉及接口变化
通常不超过 3 个 tasks、4 个文件

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

/comet

流程。

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

It applies to small-scale non-bug changes, such as copy adjustments, configuration tweaks, partial optimizations of documents or prompts.

Applicable Conditions (must meet all):

No new capability added
No architecture changes
No interface changes involved
Usually no more than 3 tasks and 4 files

Inapplicable Scenarios: If it's found during the change that capability, architecture or interface adjustments are needed, upgrade to the full

/comet

process.

流程（preset workflow，4 阶段）

Workflow (preset workflow, 4 phases)

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

开始前先定位 Comet 脚本：

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"

Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined initiation, lightweight build, lightweight verification, and archiving after verification passes.

Locate the Comet scripts first:

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"

1. 快速开启（preset open）

1. Streamlined Initiation (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 状态文件：

bash

bash "$COMET_STATE" init <name> tweak

初始化后验证状态：

bash

bash "$COMET_STATE" check <name> open

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

bash

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

Reuse Comet's open capability to create a change, but use tweak defaults: skip the

openspec-explore

long exploration and directly enter streamlined change creation.

Execute Immediately: Use the Skill tool to load the

openspec-new-change

skill. Skipping this step is prohibited.

After loading the skill, follow its guidance to create streamlined deliverables:

```
proposal.md
```
— Change motivation + objectives + scope
```
design.md
```
— Brief implementation description (no need for solution comparison)
```
tasks.md
```
— No more than 3 tasks
No delta spec required (unless the change modifies the acceptance scenarios of existing specs; once delta spec is needed, upgrade to full
```
/comet
```
)

Initialize the Comet state file:

bash

bash "$COMET_STATE" init <name> tweak

Verify the state after initialization:

bash

bash "$COMET_STATE" check <name> open

Phase guard completes the open → build transition:

bash

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

2. 轻量构建（preset build）

2. Lightweight Build (preset build)

使用 tweak 默认值：

build_mode: direct

。跳过

superpowers:brainstorming

和

superpowers: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 过渡：

bash

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

状态文件自动更新为

phase: verify

、

verify_result: pending

，然后进入验证。

Use tweak defaults:

build_mode: direct

. Skip

superpowers:brainstorming

and

superpowers:writing-plans

Before continuing or starting modifications, handle uncommitted changes according to the

comet/reference/dirty-worktree.md

protocol. If the scope exceeds tweak after attribution, follow the "Upgrade Conditions" in this document.

Execute Immediately: Execute tasks one by one as per tasks.md:

Read
```
openspec/changes/<name>/tasks.md
```
to get the list of unfinished tasks
For each unfinished task:
- Modify the target file according to the task description
- Run the project formatting command (e.g.,
```
mvn spotless:apply
```
  ,
```
npm run format
```
  , etc.)
- Run relevant tests to confirm pass
- Check the corresponding
```
- [ ]
```
  in tasks.md to
```
- [x]
```
- Commit the code with the commit message format:
```
tweak: <brief change description>
```
After all tasks are completed, explicitly run the project's relevant tests and build commands
Run the phase guard to complete the build → verify transition:

bash

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

The state file will be automatically updated to

phase: verify

verify_result: pending

, then enter verification.

3. 轻量验证（preset verify）

3. Lightweight Verification (preset verify)

复用

/comet-verify

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

立即执行： 使用 Skill 工具加载

comet-verify

技能。禁止跳过此步骤。

如规模评估进入完整验证路径，停止 tweak，升级为完整

/comet

。

验证通过后，按

/comet-verify

的规则将

.comet.yaml

的

verify_result

记录为

pass

，归档前不得跳过该状态。

Reuse

/comet-verify

. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 4 files, no delta spec, no new capability.

Execute Immediately: Use the Skill tool to load the

comet-verify

skill. Skipping this step is prohibited.

If the scale assessment enters the full verification path, stop tweak and upgrade to full

/comet

After verification passes, record

verify_result

pass

.comet.yaml

according to the

/comet-verify

rules; this state cannot be skipped before archiving.

4. 归档（preset archive）

4. Archiving (preset archive)

复用

/comet-archive

。归档前必须满足

.comet.yaml

中

verify_result: pass

。

立即执行： 使用 Skill 工具加载

comet-archive

技能进行归档。禁止跳过此步骤。

Reuse

/comet-archive

. Before archiving,

.comet.yaml

must satisfy

verify_result: pass

Execute Immediately: Use the Skill tool to load the

comet-archive

skill for archiving. Skipping this step is prohibited.

连续执行模式

Continuous Execution Mode

<IMPORTANT> Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。

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

每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill。 </IMPORTANT>

<IMPORTANT> The Tweak process is **one-time continuous execution**. After calling `/comet-tweak`, the agent must automatically complete all 4 phases without pausing to wait for user input (unless upgrade conditions are met and user confirmation is required).

Execution sequence: Streamlined Initiation → Lightweight Build → Lightweight Verification → Archiving → Completion

Immediately proceed to the next phase after completing each phase, no need for user re-input. The corresponding Comet/OpenSpec/Superpowers skills must still be called as required above within each phase. </IMPORTANT>

升级条件

Upgrade Conditions

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

/comet

：

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

升级方式：在当前 change 基础上补充 Design Doc（执行

/comet-design

），后续正常走完整流程。

Stop the tweak process and upgrade to full

/comet

when any of the following conditions are met:

Condition	Description
Changes involve 5+ files	Exceeds the scope of minor tweaks
Cross-module coordinated modifications	Requires cross-component coordination
Need to add 5+ test cases	Change complexity increases
Addition or deletion of configuration items	Configuration changes beyond value modification
Need to add new capability	Exceeds partial optimization
Need delta spec	Affects existing specifications

Upgrade method: Supplement the Design Doc based on the current change (execute

/comet-design

), then follow the full process normally.

退出条件

Exit Conditions

小改动已完成，测试通过
change 已归档
未新增 capability、架构调整或接口变化

阶段守卫：build → verify 前运行

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

，verify → archive 前按

/comet-verify

规则运行

bash "$COMET_GUARD" <change-name> verify --apply

Minor changes completed and tests passed
Change archived
No new capability added, no architecture adjustment or interface change

Phase Guard: Run

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

before build → verify, and run

bash "$COMET_GUARD" <change-name> verify --apply

according to

/comet-verify

rules before verify → archive