@rpamis/comet 0.1.0 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 rpamis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,49 +1,184 @@
-# @rpamis/comet
-
-OpenSpec + Superpowers dual-star development workflow for Claude Code.
-
-## Installation
-
-```bash
-npm install -g @rpamis/comet
-```
-
-## Quick Start
-
-```bash
-cd your-project
-comet init
-```
-
-`comet init` will:
-1. Install Comet skills to `.claude/skills/`
-2. Set up OpenSpec (if not already installed)
-3. Set up Superpowers (if not already installed)
-4. Create `docs/superpowers/` working directories
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `comet init [path]` | Initialize Comet workflow |
-| `comet --help` | Show help |
-| `comet --version` | Show version |
-
-## Skills
-
-After `comet init`, these skills are available in Claude Code:
-
-| Skill | Description |
-|-------|-------------|
-| `/comet` | Main entry — auto-detects phase and dispatches |
-| `/comet-open` | Phase 1: Open change |
-| `/comet-design` | Phase 2: Deep design |
-| `/comet-build` | Phase 3: Plan and build |
-| `/comet-verify` | Phase 4: Verify and finish |
-| `/comet-archive` | Phase 5: Archive |
-| `/comet-hotfix` | Preset: Bug fix (skip brainstorming) |
-| `/comet-tweak` | Preset: Small change (skip brainstorming and plan) |
-
-## License
-
-MIT
+# @rpamis/comet
+
+```
+ ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
+██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
+██║     ██║   ██║██╔████╔██║█████╗     ██║
+██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║
+╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║
+ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝
+```
+
+**OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
+
+OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). Superpowers handles **HOW** (technical design, planning, execution, wrap-up). Comet chains both into a five-phase automated pipeline.
+
+## Install
+
+```bash
+npm install -g @rpamis/comet
+```
+
+## Quick Start
+
+```bash
+cd your-project
+comet init
+```
+
+`comet init` will:
+
+1. Prompt you to select AI platforms (auto-detects existing configs)
+2. Choose install scope: project-level (current directory) or global (home directory)
+3. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
+4. Install [Superpowers](https://github.com/obra/superpowers) skills
+5. Deploy Comet skills to selected platforms
+6. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `comet init [path]` | Initialize Comet workflow |
+| `comet --help` | Show help |
+| `comet --version` | Show version |
+
+### init Options
+
+| Option | Description |
+|--------|-------------|
+| `--yes` | Non-interactive mode, auto-select detected platforms |
+| `--skip-existing` | Skip already installed components |
+| `--overwrite` | Overwrite already installed components |
+
+## Supported Platforms
+
+`comet init` supports 28 AI coding platforms:
+
+| Platform | Skills Dir | Platform | Skills Dir |
+|----------|-----------|----------|-----------|
+| Claude Code | `.claude/` | Cursor | `.cursor/` |
+| Codex | `.codex/` | OpenCode | `.opencode/` |
+| Windsurf | `.windsurf/` | Cline | `.cline/` |
+| RooCode | `.roo/` | Continue | `.continue/` |
+| GitHub Copilot | `.github/` | Gemini CLI | `.gemini/` |
+| Amazon Q Developer | `.amazonq/` | Qwen Code | `.qwen/` |
+| Kilo Code | `.kilocode/` | Auggie | `.augment/` |
+| Kiro | `.kiro/` | Lingma | `.lingma/` |
+| Junie | `.junie/` | CodeBuddy | `.codebuddy/` |
+| CoStrict | `.cospec/` | Crush | `.crush/` |
+| Factory Droid | `.factory/` | iFlow | `.iflow/` |
+| Pi | `.pi/` | Qoder | `.qoder/` |
+| Antigravity | `.agent/` | Bob Shell | `.bob/` |
+| ForgeCode | `.forge/` | Trae | `.trae/` |
+
+## Skills
+
+After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
+
+### Comet Skills
+
+| Skill | Description |
+|-------|-------------|
+| `/comet` | Main entry — auto-detects phase and dispatches to sub-commands |
+| `/comet-open` | Phase 1: Open a change (proposal, design, task breakdown) |
+| `/comet-design` | Phase 2: Deep design (brainstorming, Design Doc) |
+| `/comet-build` | Phase 3: Plan and build (implementation plan, code commits) |
+| `/comet-verify` | Phase 4: Verify and finish (testing, verification report) |
+| `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation) |
+| `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
+| `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
+
+### OpenSpec Skills
+
+Spec lifecycle management: propose, explore, sync, verify, archive, and more.
+
+### Superpowers Skills
+
+Development methodology: brainstorming, TDD, subagent-driven development, code review, plan writing, and more.
+
+## Workflow
+
+```
+/comet
+  ↓ auto-detect
+/comet-open ——→ /comet-design ——→ /comet-build ——→ /comet-verify ——→ /comet-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/comet-hotfix (preset path, skips brainstorming)
+  open ——→ build ——→ verify ——→ archive
+
+/comet-tweak (preset path, skips brainstorming and full plan)
+  open ——→ lightweight build ——→ light verify ——→ archive
+```
+
+### Five Phases
+
+| Phase | Command | Owner | Artifacts |
+|-------|---------|-------|-----------|
+| 1. Open | `/comet-open` | OpenSpec | proposal.md, design.md, tasks.md |
+| 2. Deep Design | `/comet-design` | Superpowers | Design Doc, delta spec |
+| 3. Plan & Build | `/comet-build` | Superpowers | Implementation plan, code commits |
+| 4. Verify & Finish | `/comet-verify` | Both | Verification report, branch handling |
+| 5. Archive | `/comet-archive` | OpenSpec | delta→main spec sync, archive |
+
+### Core Principles
+
+- **Brainstorming is non-skippable** — every change must go through deep design (except hotfix/tweak)
+- **Delta specs are living documents** — freely editable during Phase 3, synced at archive
+- **Keep tasks.md in sync** — check off each task as completed
+- **Commit frequently** — one commit per task, message reflects design intent
+- **Verify before archive** — `/comet-verify` must pass before `/comet-archive`
+
+## Project Structure
+
+```
+your-project/
+├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
+│   ├── comet/SKILL.md
+│   ├── comet-*/SKILL.md
+│   ├── openspec-*/SKILL.md
+│   └── brainstorming/SKILL.md
+├── openspec/                    # OpenSpec — WHAT
+│   ├── config.yaml
+│   └── changes/
+│       └── <name>/
+│           ├── .openspec.yaml
+│           ├── proposal.md
+│           ├── design.md
+│           ├── specs/<capability>/spec.md
+│           └── tasks.md
+└── docs/superpowers/            # Superpowers — HOW
+    ├── specs/                   # Design documents
+    └── plans/                   # Implementation plans
+```
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/benym/comet.git
+cd comet
+
+# Install dependencies
+pnpm install
+
+# Dev mode (watch)
+pnpm dev
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+```
+
+## Security
+
+- Pre-publish scan for API keys, secrets, tokens, and private keys
+- `.npmignore` prevents source code and config files from entering the npm package
+- `.gitignore` covers secrets, credentials, IDE configs, and more
+
+## License
+
+MIT

package/assets/manifest.json

@@ -1,13 +1,13 @@
-{
-  "version": "0.1.0",
-  "skills": [
-    "comet/SKILL.md",
-    "comet-open/SKILL.md",
-    "comet-design/SKILL.md",
-    "comet-build/SKILL.md",
-    "comet-verify/SKILL.md",
-    "comet-archive/SKILL.md",
-    "comet-hotfix/SKILL.md",
-    "comet-tweak/SKILL.md"
-  ]
-}
+{
+  "version": "0.1.0",
+  "skills": [
+    "comet/SKILL.md",
+    "comet-open/SKILL.md",
+    "comet-design/SKILL.md",
+    "comet-build/SKILL.md",
+    "comet-verify/SKILL.md",
+    "comet-archive/SKILL.md",
+    "comet-hotfix/SKILL.md",
+    "comet-tweak/SKILL.md"
+  ]
+}

package/assets/skills/comet/SKILL.md

@@ -158,6 +158,18 @@ comet:
 
 ## 快速参考
 
+### 脚本定位
+
+Comet 阶段守卫脚本 `comet-guard.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
+**不硬编码平台路径**，运行时通过以下命令自定位：
+
+```bash
+COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
+bash "$COMET_GUARD" <change-name> <phase>
+```
+
+后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
+
 ### 文件结构
 
 ```

package/assets/skills/comet/scripts/comet-guard.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# Comet Phase Guard — validates exit conditions before phase transitions
+# Usage: comet-guard.sh <change-name> <from-phase>
+# Phases: open, design, build, verify, archive
+# Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
+
+set -euo pipefail
+
+CHANGE="$1"
+PHASE="$2"
+CHANGE_DIR="openspec/changes/$CHANGE"
+
+red() { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+warn() { echo -e "\033[33m$1\033[0m" >&2; }
+
+BLOCK=0
+check() {
+  local desc="$1"
+  shift
+  if "$@" 2>/dev/null; then
+    green "  [PASS] $desc"
+  else
+    red "  [FAIL] $desc"
+    BLOCK=1
+  fi
+}
+
+# --- Helper functions ---
+
+tasks_all_done() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  [ -f "$tasks" ] || return 1
+  grep -q '\- \[x\]' "$tasks" || return 1
+  ! grep -q '\- \[ \]' "$tasks"
+}
+
+tasks_has_any() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
+}
+
+yaml_has_field() {
+  local field="$1"
+  local yaml="$CHANGE_DIR/.openspec.yaml"
+  [ -f "$yaml" ] && grep -q "^${field}:" "$yaml"
+}
+
+yaml_field_value() {
+  local field="$1"
+  local yaml="$CHANGE_DIR/.openspec.yaml"
+  if [ -f "$yaml" ]; then
+    # Escape dots for literal match (YAML field names contain dots)
+    local escaped
+    escaped=$(echo "$field" | sed 's/\./\\./g')
+    grep "^${escaped}:" "$yaml" | sed "s/^${escaped}: *//" | tr -d '"' | tr -d "'"
+  fi
+}
+
+file_nonempty() {
+  [ -f "$1" ] && [ -s "$1" ]
+}
+
+maven_compiles() {
+  mvn compile -q 2>/dev/null
+}
+
+verify_result_is_pass() {
+  local result
+  result=$(yaml_field_value "comet.verify_result" 2>/dev/null || true)
+  [ "$result" = "pass" ]
+}
+
+# --- Phase-specific checks ---
+
+guard_open() {
+  echo "=== Guard: open → design ===" >&2
+
+  check "proposal.md exists and non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
+  check "tasks.md exists and non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
+  check "tasks.md has at least one task" tasks_has_any
+}
+
+guard_design() {
+  echo "=== Guard: design → build ===" >&2
+
+  local design_doc
+  design_doc=$(yaml_field_value "comet.design_doc" 2>/dev/null || true)
+
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "tasks.md exists" file_nonempty "$CHANGE_DIR/tasks.md"
+
+  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
+    check "Design Doc ($design_doc) exists" file_nonempty "$design_doc"
+  else
+    warn "  [WARN] No design_doc recorded in .openspec.yaml"
+  fi
+}
+
+guard_build() {
+  echo "=== Guard: build → verify ===" >&2
+
+  check "tasks.md all tasks checked" tasks_all_done
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "Maven compile passes" maven_compiles
+}
+
+guard_verify() {
+  echo "=== Guard: verify → archive ===" >&2
+
+  check "verify_result is pass" verify_result_is_pass
+  check "tasks.md all tasks checked" tasks_all_done
+  check "Maven compile passes" maven_compiles
+}
+
+guard_archive() {
+  echo "=== Guard: archive completeness ===" >&2
+
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "tasks.md all tasks checked" tasks_all_done
+}
+
+# --- Main ---
+
+case "$PHASE" in
+  open)     guard_open ;;
+  design)   guard_design ;;
+  build)    guard_build ;;
+  verify)   guard_verify ;;
+  archive)  guard_archive ;;
+  *)
+    red "Unknown phase: $PHASE"
+    echo "Valid phases: open, design, build, verify, archive" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$BLOCK" -eq 1 ]; then
+  echo "" >&2
+  red "BLOCKED — fix failing checks before proceeding to next phase"
+  exit 1
+else
+  echo "" >&2
+  green "ALL CHECKS PASSED — ready for next phase"
+  exit 0
+fi

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

@@ -93,6 +93,7 @@ brainstorming → delta spec → 实施（增量修改）→ 验证 → 主 spec
 - 关联 design doc 已标注归档状态
 - 关联 plan 已标注归档状态
 - `.openspec.yaml` 中 `comet.archived` 已记录为 `true`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
 
 归档完成后，在归档目录的 `.openspec.yaml` 中合并更新：
 

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

@@ -106,6 +106,7 @@ comet:
 - 代码已提交
 - 测试通过
 - `.openspec.yaml` 中 `comet.phase` 已更新为 `verify`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
 
 退出前合并更新：
 

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

@@ -67,6 +67,7 @@ design.md（阶段 1，OpenSpec）      → 高层架构决策
 
 - Design Doc 已创建并保存
 - 如有新能力则 delta spec 已创建
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> design`，全部 PASS 后才允许流转
 
 ## 自动流转
 

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

@@ -128,3 +128,4 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
+- **阶段守卫**：build → verify 前运行 `bash $COMET_GUARD <change-name> build`，verify → archive 前运行 `bash $COMET_GUARD <change-name> verify`

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

@@ -78,6 +78,7 @@ comet:
 ## 退出条件
 
 - proposal.md、design.md、tasks.md 均已创建且内容完整
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> open`，全部 PASS 后才允许流转
 
 ## 自动流转
 

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

@@ -1,117 +1,118 @@
----
-name: comet-tweak
-description: "Comet 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → lightweight build → light verify → archive。适用于文案、配置、文档或 prompt 的局部优化。"
----
-
-# Comet 预设路径：Tweak
-
-Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它复用 open、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
-
-适用于非 bug 的小范围变更，例如文案调整、配置调整、文档或 prompt 的局部优化。
-
-**适用条件**（必须全部满足）：
-1. 不新增 capability
-2. 不改变架构
-3. 不涉及接口变化
-4. 通常不超过 3 个 tasks、5 个文件
-
-**不适用**：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 `/comet` 流程。
-
----
-
-## 流程（preset workflow，4 阶段）
-
-执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
-
-### 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`）
-
-在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并 tweak 状态：
-
-```yaml
-comet:
-  workflow: tweak
-  phase: build
-  design_doc: null
-  plan: null
-  build_mode: direct
-  verify_mode: light
-  verify_result: pending
-  verified_at: null
-  archived: false
-```
-
-### 2. 轻量构建（preset build）
-
-使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
-
-**立即执行：** 按 tasks.md 逐个执行任务：
-
-1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
-2. 对每个未完成任务：
-   - 根据任务描述修改目标文件
-   - 运行 `mvn spotless:apply` 格式化
-   - 运行相关测试确认通过
-   - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
-   - 提交代码，commit message 格式：`tweak: <简述变更>`
-3. 全部任务完成后进入验证
-
-### 3. 轻量验证（preset verify）
-
-复用 `/comet-verify`。Tweak 必须保持轻量验证条件：≤ 3 tasks、≤ 5 files、无 delta spec、无新 capability。
-
-**立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
-
-如规模评估进入完整验证路径，停止 tweak，升级为完整 `/comet`。
-
-验证通过后，按 `/comet-verify` 的规则将 `comet.verify_result` 记录为 `pass`，归档前不得跳过该状态。
-
-### 4. 归档（preset archive）
-
-复用 `/comet-archive`。归档前必须满足 `comet.verify_result: pass`。
-
-**立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
-
----
-
-## 连续执行模式
-
-<IMPORTANT>
-Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。
-
-执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
-
-每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill。
-</IMPORTANT>
-
----
-
-## 升级条件
-
-执行过程中出现以下情况时，停止 tweak 流程，升级为完整 `/comet`：
-
-1. 需要新增 capability
-2. 需要架构调整
-3. 需要接口变化
-4. 影响范围扩大到 > 5 个文件
-5. 任务数超过 3 个
-6. 需要 delta spec
-
-升级方式：在当前 change 基础上补充 Design Doc（执行 `/comet-design`），后续正常走完整流程。
-
----
-
-## 退出条件
-
-- 小改动已完成，测试通过
-- change 已归档
-- 未新增 capability、架构调整或接口变化
+---
+name: comet-tweak
+description: "Comet 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → lightweight build → light verify → archive。适用于文案、配置、文档或 prompt 的局部优化。"
+---
+
+# Comet 预设路径：Tweak
+
+Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它复用 open、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
+
+适用于非 bug 的小范围变更，例如文案调整、配置调整、文档或 prompt 的局部优化。
+
+**适用条件**（必须全部满足）：
+1. 不新增 capability
+2. 不改变架构
+3. 不涉及接口变化
+4. 通常不超过 3 个 tasks、5 个文件
+
+**不适用**：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 `/comet` 流程。
+
+---
+
+## 流程（preset workflow，4 阶段）
+
+执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
+
+### 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`）
+
+在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并 tweak 状态：
+
+```yaml
+comet:
+  workflow: tweak
+  phase: build
+  design_doc: null
+  plan: null
+  build_mode: direct
+  verify_mode: light
+  verify_result: pending
+  verified_at: null
+  archived: false
+```
+
+### 2. 轻量构建（preset build）
+
+使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
+
+**立即执行：** 按 tasks.md 逐个执行任务：
+
+1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
+2. 对每个未完成任务：
+   - 根据任务描述修改目标文件
+   - 运行 `mvn spotless:apply` 格式化
+   - 运行相关测试确认通过
+   - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
+   - 提交代码，commit message 格式：`tweak: <简述变更>`
+3. 全部任务完成后进入验证
+
+### 3. 轻量验证（preset verify）
+
+复用 `/comet-verify`。Tweak 必须保持轻量验证条件：≤ 3 tasks、≤ 5 files、无 delta spec、无新 capability。
+
+**立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
+
+如规模评估进入完整验证路径，停止 tweak，升级为完整 `/comet`。
+
+验证通过后，按 `/comet-verify` 的规则将 `comet.verify_result` 记录为 `pass`，归档前不得跳过该状态。
+
+### 4. 归档（preset archive）
+
+复用 `/comet-archive`。归档前必须满足 `comet.verify_result: pass`。
+
+**立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
+
+---
+
+## 连续执行模式
+
+<IMPORTANT>
+Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。
+
+执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
+
+每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill。
+</IMPORTANT>
+
+---
+
+## 升级条件
+
+执行过程中出现以下情况时，停止 tweak 流程，升级为完整 `/comet`：
+
+1. 需要新增 capability
+2. 需要架构调整
+3. 需要接口变化
+4. 影响范围扩大到 > 5 个文件
+5. 任务数超过 3 个
+6. 需要 delta spec
+
+升级方式：在当前 change 基础上补充 Design Doc（执行 `/comet-design`），后续正常走完整流程。
+
+---
+
+## 退出条件
+
+- 小改动已完成，测试通过
+- change 已归档
+- 未新增 capability、架构调整或接口变化
+- **阶段守卫**：build → verify 前运行 `bash $COMET_GUARD <change-name> build`，verify → archive 前运行 `bash $COMET_GUARD <change-name> verify`

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

@@ -114,6 +114,7 @@ comet:
 - 验证报告通过
 - 分支已处理
 - `.openspec.yaml` 中 `comet.verify_result` 已记录为 `pass`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> verify`，全部 PASS 后才允许流转
 
 退出前合并更新：
 

package/bin/comet.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-
-import '../dist/cli/index.js';
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@rpamis/comet",
-  "version": "0.1.0",
-  "description": "OpenSpec + Superpowers dual-star development workflow",
-  "keywords": [
-    "comet",
-    "openspec",
-    "superpowers",
-    "skills",
-    "workflow"
-  ],
-  "license": "MIT",
-  "author": "benym",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "comet": "./bin/comet.js"
-  },
-  "files": [
-    "dist",
-    "bin",
-    "assets",
-    "scripts/postinstall.js",
-    "!dist/**/*.test.js",
-    "!dist/**/__tests__"
-  ],
-  "scripts": {
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build",
-    "postinstall": "node scripts/postinstall.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "devDependencies": {
-    "@types/node": "^24.2.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
-  },
-  "dependencies": {
-    "@inquirer/prompts": "^8.4.3",
-    "commander": "^14.0.0"
-  }
-}
+{
+  "name": "@rpamis/comet",
+  "version": "0.1.2",
+  "description": "OpenSpec + Superpowers dual-star development workflow",
+  "keywords": [
+    "comet",
+    "openspec",
+    "superpowers",
+    "skills",
+    "workflow"
+  ],
+  "license": "MIT",
+  "author": "benym",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "comet": "./bin/comet.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "assets",
+    "scripts/postinstall.js",
+    "!dist/**/*.test.js",
+    "!dist/**/__tests__"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "node scripts/prepublish-check.js && pnpm run build",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.3",
+    "commander": "^14.0.0"
+  }
+}

package/scripts/postinstall.js

@@ -1,44 +1,44 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script that hints about comet init.
- *
- * The tip is suppressed when:
- * - CI=true environment variable is set
- * - COMET_NO_HINTS=1 environment variable is set
- * - dist/ directory doesn't exist (dev setup scenario)
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-function shouldSkip() {
-  if (process.env.CI === 'true' || process.env.CI === '1') return true;
-  if (process.env.COMET_NO_HINTS === '1') return true;
-  return false;
-}
-
-async function distExists() {
-  try {
-    const stat = await fs.stat(path.join(__dirname, '..', 'dist'));
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function main() {
-  try {
-    if (shouldSkip()) return;
-    if (!(await distExists())) return;
-    console.log(`\nTip: Run 'comet init' to set up Comet workflow in your project`);
-  } catch {
-    // Never break npm install
-  }
-}
-
-main().catch(() => process.exit(0));
+#!/usr/bin/env node
+
+/**
+ * Postinstall script that hints about comet init.
+ *
+ * The tip is suppressed when:
+ * - CI=true environment variable is set
+ * - COMET_NO_HINTS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function shouldSkip() {
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (process.env.COMET_NO_HINTS === '1') return true;
+  return false;
+}
+
+async function distExists() {
+  try {
+    const stat = await fs.stat(path.join(__dirname, '..', 'dist'));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  try {
+    if (shouldSkip()) return;
+    if (!(await distExists())) return;
+    console.log(`\nTip: Run 'comet init' to set up Comet workflow in your project`);
+  } catch {
+    // Never break npm install
+  }
+}
+
+main().catch(() => process.exit(0));