@rpamis/comet 0.1.7 → 0.2.0

package/assets/skills/comet-tweak/SKILL.md

@@ -1,154 +1,122 @@
----
-name: comet-tweak
-description: "Comet preset path: Non-bug small changes (tweak). Skip brainstorming and full plan, directly open → lightweight build → light verify → archive. Applicable for copy, configuration, documentation or prompt local optimization."
----
-
-# Comet Preset Path: Tweak
-
-Tweak is a preset workflow of Comet's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
-
-Applicable for small-scale non-bug changes, such as copy adjustments, configuration adjustments, documentation or prompt local optimization.
-
-**Applicable conditions** (all must be met):
-1. No new capability
-2. No architecture changes
-3. No interface changes involved
-4. Usually not exceeding 3 tasks, 5 files
-
-**Not applicable**: If change process discovers need for capability, architecture, or interface adjustments, should upgrade to full `/comet` workflow.
-
----
-
-## Process (preset workflow, 4 phases)
-
-### 0. Entry State Verification (Entry Check)
-
-Before performing any operations, verify current state:
-
-**Checklist:**
-1. `openspec/changes/<name>/` directory does not exist, or directory exists but `.comet.yaml` does not exist (no conflict)
-
-**Verification method:**
-- `test -d openspec/changes/<name>` to check directory
-- If directory exists, `test -f openspec/changes/<name>/.comet.yaml` to check config file
-- If `.comet.yaml` exists, read `phase` to check if it's an incomplete tweak
-
-**Failure output (has conflict):**
-```
-[HARD STOP] Entry check failed for comet-tweak
-  Expected: openspec/changes/<name>/.comet.yaml does not exist (new change)
-  Actual:   .comet.yaml exists with phase=<actual-value>
-  Suggestion: Pick a different change name, or check if an existing tweak is in progress.
-```
-
-Proceed to process steps only after verification passes.
-
-Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, archive after verification passes.
-
-### 1. Quick Open (preset open)
-
-Reuse Comet open capability to create change, but use tweak defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
-
-**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
-
-After the skill loads, follow its guidance to create streamlined artifacts:
-  - `proposal.md` — change motivation + goals + scope
-  - `design.md` — brief implementation description (no solution comparison needed)
-  - `tasks.md` — not exceeding 3 tasks
-- **No delta spec needed** (unless change changes existing spec acceptance scenarios; once delta spec needed, upgrade to full `/comet`)
-
-Create independent `.comet.yaml` file under `openspec/changes/<name>/`:
-
-```yaml
-workflow: tweak
-phase: build
-design_doc: null
-plan: null
-build_mode: direct
-isolation: branch
-verify_mode: light
-verify_result: pending
-verified_at: null
-archived: false
-```
-
-【Write verification】After creation completion, must verify:
-  cat openspec/changes/<name>/.comet.yaml
-  Confirm workflow line value is "tweak"
-  Confirm phase line value is "build"
-  Confirm design_doc line value is "null"
-  Confirm plan line value is "null"
-  Confirm build_mode line value is "direct"
-  Confirm isolation line value is "branch"
-  Confirm verify_mode line value is "light"
-  Confirm verify_result line value is "pending"
-  Confirm verified_at line value is "null"
-  Confirm archived line value is "false"
-  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
-
-### 2. Lightweight Build (preset build)
-
-Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
-
-**Immediately execute:** Execute tasks one by one according to tasks.md:
-
-1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
-2. For each incomplete task:
-   - Modify target file according to task description
-   - Run `mvn spotless:apply` to format
-   - Run related tests to confirm pass
-   - Check corresponding `- [ ]` to `- [x]` in tasks.md
-   - Commit code, commit message format: `tweak: <brief change description>`
-3. After all tasks complete, enter verification
-
-### 3. Lightweight Verification (preset verify)
-
-Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 5 files, no delta spec, no new capability.
-
-**Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
-
-If scale assessment enters full verification path, stop tweak, upgrade to full `/comet`.
-
-After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
-
-### 4. Archive (preset archive)
-
-Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
-
-**Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
-
----
-
-## Continuous Execution Mode
-
-<IMPORTANT>
-Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
-
-Execution order: quick open → lightweight build → lightweight verification → archive → complete
-
-After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
-</IMPORTANT>
-
----
-
-## Upgrade Conditions
-
-When the following situations occur during execution, stop tweak workflow, upgrade to full `/comet`:
-
-1. Need new capability
-2. Need architecture adjustments
-3. Need interface changes
-4. Impact scope expands to > 5 files
-5. Task count exceeds 3
-6. Need delta spec
-
-Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
-
----
-
-## Exit Conditions
-
-- Small change completed, tests pass
-- Change archived
-- No new capability, architecture adjustments, or interface changes
-- **Phase guard**: Before build → verify run `bash $COMET_GUARD <change-name> build`, before verify → archive run `bash $COMET_GUARD <change-name> verify`
+---
+name: comet-tweak
+description: "Comet preset path: Non-bug small changes (tweak). Skip brainstorming and full plan, directly open → lightweight build → light verify → archive. Applicable for copy, configuration, documentation or prompt local optimization."
+---
+
+# Comet Preset Path: Tweak
+
+Tweak is a preset workflow of Comet's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
+
+Applicable for small-scale non-bug changes, such as copy adjustments, configuration adjustments, documentation or prompt local optimization.
+
+**Applicable conditions** (all must be met):
+1. No new capability
+2. No architecture changes
+3. No interface changes involved
+4. Usually not exceeding 3 tasks, 5 files
+
+**Not applicable**: If change process discovers need for capability, architecture, or interface adjustments, should upgrade to full `/comet` workflow.
+
+---
+
+## Process (preset workflow, 4 phases)
+
+### 0. Entry State Verification (Entry Check)
+
+Execute entry verification:
+
+```bash
+COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+bash "$COMET_STATE" check <name> open
+```
+
+Proceed to process steps after verification passes. The script outputs specific failure reasons when verification fails.
+
+Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, archive after verification passes.
+
+### 1. Quick Open (preset open)
+
+Reuse Comet open capability to create change, but use tweak defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to create streamlined artifacts:
+  - `proposal.md` — change motivation + goals + scope
+  - `design.md` — brief implementation description (no solution comparison needed)
+  - `tasks.md` — not exceeding 3 tasks
+- **No delta spec needed** (unless change changes existing spec acceptance scenarios; once delta spec needed, upgrade to full `/comet`)
+
+Initialize Comet state file:
+
+```bash
+bash "$COMET_STATE" init <name> tweak
+```
+
+### 2. Lightweight Build (preset build)
+
+Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
+
+**Immediately execute:** Execute tasks one by one according to tasks.md:
+
+1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
+2. For each incomplete task:
+   - Modify target file according to task description
+   - Run project formatter (e.g., `mvn spotless:apply`, `npm run format`)
+   - Run related tests to confirm pass
+   - Check corresponding `- [ ]` to `- [x]` in tasks.md
+   - Commit code, commit message format: `tweak: <brief change description>`
+3. After all tasks complete, enter verification
+
+### 3. Lightweight Verification (preset verify)
+
+Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 5 files, no delta spec, no new capability.
+
+**Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
+
+If scale assessment enters full verification path, stop tweak, upgrade to full `/comet`.
+
+After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
+
+### 4. Archive (preset archive)
+
+Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
+
+**Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
+
+---
+
+## Continuous Execution Mode
+
+<IMPORTANT>
+Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
+
+Execution order: quick open → lightweight build → lightweight verification → archive → complete
+
+After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
+</IMPORTANT>
+
+---
+
+## Upgrade Conditions
+
+Upgrade to full `/comet` when **any** of the following conditions are met:
+
+| Condition | Explanation |
+|-----------|-------------|
+| Change involves **5+ files** | Exceeds small change scope |
+| Cross-module coordination required | Needs coordination across components |
+| **5+** new test cases needed | Change complexity increasing |
+| Config item additions or deletions | Non-value config changes |
+| New capability needed | Exceeds local optimization |
+| Delta spec needed | Affects existing specifications |
+
+Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
+
+---
+
+## Exit Conditions
+
+- Small change completed, tests pass
+- Change archived
+- No new capability, architecture adjustments, or interface changes
+- **Phase guard**: Before build → verify run `bash $COMET_GUARD <change-name> build`, before verify → archive run `bash $COMET_GUARD <change-name> verify`

package/assets/skills/comet-verify/SKILL.md

@@ -14,44 +14,24 @@ description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Ver
 
 ### 0. Entry State Verification (Entry Check)
 
-Before performing any operations, read and verify the current state:
+Execute entry verification:
 
-**Checklist:**
-1. `openspec/changes/<name>/.comet.yaml` exists
-2. `phase` field value is `"verify"`
-3. `verify_result` field is `"pending"` or null (not yet verified)
-
-**Verification method:**
-- `cat openspec/changes/<name>/.comet.yaml` to read all fields
-- If `verify_result` is already `"pass"`, this change has already been verified
-
-**Failure output:**
-```
-[HARD STOP] Entry check failed for comet-verify
-  Expected: phase=verify, verify_result=pending|null
-  Actual:   phase=<actual-value>, verify_result=<actual-value>
-  Suggestion: Run comet-build first, or this change was already verified.
+```bash
+COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+bash "$COMET_STATE" check <name> verify
 ```
 
-Proceed to Step 1 only after verification passes.
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
 ### 1. Change Scale Assessment
 
-Determine change scale based on the following metrics:
+Execute scale assessment:
 
-| Metric | Small (lightweight verification) | Large (full verification) |
-|------|-------------------------------|--------------------------|
-| tasks.md task count | ≤ 3 | > 3 |
-| Changed file count (git diff --stat) | ≤ 5 | > 5 |
-| Has delta spec | No | Yes |
-| New capability added | No | Yes |
-
-**Decision rule**: Any metric hitting "large" → full verification. All hitting "small" → lightweight verification.
-
-After determination, record actual verification mode in `openspec/changes/<name>/.comet.yaml`. `verify_mode` only allows one of the following values:
+```bash
+bash "$COMET_STATE" scale <name>
+```
 
-- `light`
-- `full`
+Script automatically counts tasks, delta specs, and changed files to determine whether to use light or full verification mode, and sets the verify_mode field.
 
 ### 2a. Lightweight Verification (Small Changes)
 
@@ -59,7 +39,7 @@ When scale assessment result is "small", skip `openspec-verify-change`, directly
 
 1. All tasks in tasks.md completed `[x]`
 2. Changed files consistent with tasks.md description (`git diff --stat`对照 tasks content)
-3. Build passes (for Maven projects, first execute `mvn spotless:apply`, then execute `mvn compile` or equivalent command)
+3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
 4. Related tests pass
 5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
 
@@ -109,9 +89,7 @@ After the skill loads, follow its guidance to complete. Branch handling options:
 4. Discard work
 
 **Confirmation items**:
-- Maven test or build commands have executed `mvn spotless:apply`
 - All tests pass
-- No remaining spotless formatting issues
 - No hardcoded secrets or security issues
 
 ## Exit Conditions

package/assets/skills-zh/comet/SKILL.md

@@ -5,7 +5,7 @@ description: "Comet — OpenSpec + Superpowers 双星开发流程。用 /comet
 
 # Comet — OpenSpec + Superpowers 双星开发流程
 
-OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。OpenSpec 负责 WHAT，Superpowers 负责 HOW。
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
 
 ```
 OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
@@ -14,105 +14,89 @@ Superpowers 负责 HOW — 技术设计、计划、执行、收尾
 
 **核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
 
-<IMPORTANT>
-## 阶段衔接
-
-单次 `/comet` 调用会从检测到的阶段开始执行，并在每个阶段退出条件满足后提示或进入下一阶段。
-
-流转链：open → design → build → verify → archive
-
-需要用户参与的节点：
-1. brainstorming 过程中确认设计方案
-2. build 阶段选择执行方式
-3. verify 不通过时决定修复或接受偏差
-4. finishing-branch 选择分支处理方式
-5. 遇到升级条件（hotfix/tweak → 完整流程）
+---
 
-agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
-</IMPORTANT>
+## 决策核心（Decision Core）
 
-## 阶段自动检测
+agent 做决策只需读本节，参考附录按需查阅。
 
-### Step 0: 活跃 Change 发现
+### 阶段自动检测
 
-**立即执行：**
+**Step 0: 活跃 Change 发现**
 
 1. 运行 `openspec list --json` 获取所有活跃 change
 2. 对每个 change，检查 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 匹配关联文件，判断阶段和进度
 
-**分支逻辑：**
-
 | 情况 | 行为 |
 |------|------|
 | 无活跃 change | → 调用 `/comet-open` |
-| 恰好 1 个活跃 change | → 自动选中，进入阶段判定（Step 1） |
+| 恰好 1 个活跃 change | → 自动选中，进入 Step 1 |
 | 多个活跃 change | → 列出清单让用户选择 |
 
-**多 change 选择**：使用 AskUserQuestion 展示，格式示例：
+**Preset 检测**：
+- 用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 `/comet-hotfix`
+- 用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 `/comet-tweak`
 
-```
-| # | Change 名称 | 当前阶段 | 任务进度 |
-|---|------------|---------|---------|
-| 1 | xxx-feature | Build | 3/5 tasks |
-| 2 | yyy-fix | Design | No design doc |
-```
+**Step 1: 读取 `.comet.yaml` 状态元数据**
 
-用户选择后，对选中的 change 进入阶段判定。
+优先读取 `openspec/changes/<name>/.comet.yaml`。不存在时回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
 
-**Preset 检测**：
-- 如用户明确描述为 bug fix / 热修复，且满足 hotfix 适用条件，直接调用 `/comet-hotfix`（跳过选择）。
-- 如用户明确描述为文案、配置、文档、prompt 或小范围非 bug 调整，且满足 tweak 适用条件，直接调用 `/comet-tweak`（跳过选择）。
+**Step 2: 阶段判定**（按顺序，命中即停）
 
-### Step 1: Comet 状态元数据读取
+1. `archived: true` 或 change 已移入 archive → 流程已完成
+2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`
+3. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
+4. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
+5. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
+6. 无活跃 change 或状态无法判定 → `/comet-open`
 
-优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+如果元数据与文件状态冲突，以文件状态为准，修正 `.comet.yaml` 后继续。
 
-推荐元数据结构：
+### 预设升级条件
 
-```yaml
-workflow: full
-phase: build
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
-build_mode: subagent-driven-development
-isolation: branch
-verify_mode: light
-verify_result: pending
-verified_at: null
-archived: false
-```
+**hotfix → full**（满足任一即升级）：
+- 改动涉及 **3+ 文件**
+- 涉及架构变更（新模块、新接口、新依赖）
+- 涉及数据库 schema 变更
+- 修复引入新的 public API
+- 修复范围超出单一函数/模块
 
-字段含义：
+**tweak → full**（满足任一即升级）：
+- 改动涉及 **5+ 文件**
+- 涉及多个模块的协调修改
+- 需要新增测试用例 **5+**
+- 涉及配置项的新增或删除（非值修改）
 
-| 字段 | 含义 |
-|------|------|
-| `workflow` | `full`、`hotfix` 或 `tweak` |
-| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive` |
-| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
-| `plan` | 关联的 Superpowers Plan 路径，可为空 |
-| `build_mode` | 已选择的执行方式，可为空 |
-| `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
-| `verify_mode` | `light` 或 `full`，可为空 |
-| `verify_result` | `pending`、`pass` 或 `fail` |
-| `verified_at` | 验证通过时间，可为空 |
-| `archived` | change 是否已归档 |
+### 错误处理速查
 
-### Step 2: 阶段判定
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `bash $COMET_STATE set` 修正后继续 |
+| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
+
+### 阶段衔接
 
-对选中的 change，按以下顺序判断当前状态：
+<IMPORTANT>
+单次 `/comet` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
 
-1. **`archived: true` 或 change 已移入 archive** → 流程已完成
-2. **`verify_result: pass` 且 `archived` 不是 `true`** → 调用 `/comet-archive`
-3. **`phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
-4. **`phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
-5. **`phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
-6. **无活跃 change 或状态无法判定** → 调用 `/comet-open`
+流转链：open → design → build → verify → archive
 
-如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
+需要用户参与的节点：
+1. brainstorming 确认设计方案
+2. build 阶段选择执行方式
+3. verify 不通过时决定修复或接受偏差
+4. finishing-branch 选择分支处理方式
+5. 遇到升级条件（hotfix/tweak → 完整流程）
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
+</IMPORTANT>
 
 ---
 
-## 子命令
+## 子命令速查
 
 | 命令 | 阶段 | 归属 | 产物 |
 |------|------|------|------|
@@ -124,10 +108,6 @@ archived: false
 | `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
 | `/comet-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
 
----
-
-## 流程图
-
 ```
 /comet
   ↓ 自动检测
@@ -145,28 +125,44 @@ archived: false
 
 ---
 
-## 错误处理
+## 参考附录（Reference Appendix）
 
-| 场景 | 处理方式 |
-|------|---------|
-| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
-| 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
-| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
-| change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
+### .comet.yaml 字段说明
 
----
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
 
-## 快速参考
+| 字段 | 含义 |
+|------|------|
+| `workflow` | `full`、`hotfix` 或 `tweak` |
+| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive` |
+| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
+| `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `build_mode` | 已选择的执行方式，可为空 |
+| `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
+| `verify_mode` | `light` 或 `full`，可为空 |
+| `verify_result` | `pending`、`pass` 或 `fail` |
+| `verified_at` | 验证通过时间，可为空 |
+| `archived` | change 是否已归档 |
 
 ### 脚本定位
 
-Comet 阶段守卫脚本 `comet-guard.sh` 和归档脚本 `comet-archive.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
-**不硬编码平台路径**，运行时通过以下命令自定位：
+Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
 
 ```bash
-COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
-bash "$COMET_GUARD" <change-name> <phase>
+COMET_GUARD="${COMET_GUARD:-$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)}"
+COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
 ```
 
 **自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
@@ -178,11 +174,10 @@ bash "$COMET_GUARD" <change-name> <phase> --apply
 **归档脚本**：一键完成归档全部步骤：
 
 ```bash
-COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
 bash "$COMET_ARCHIVE" <change-name>
 ```
 
-后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
+加载 comet 后，agent 应执行以上三条变量赋值一次，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_ARCHIVE`。
 
 ### 文件结构
 
@@ -215,5 +210,5 @@ docs/superpowers/                      # Superpowers — HOW
 6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
 7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
 8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
-9. **增量修改已有功能** — 直接 open 新 change，brainstorming 会读取已有 main spec 作为上下文
+9. **修改已有功能** — 直接 open 新 change 即可
 10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程