@rpamis/comet 0.1.4 → 0.1.6

package/README.md

@@ -30,10 +30,11 @@ comet init
 
 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
+3. Select language for Comet skills: English or 中文
+4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
+5. Install [Superpowers](https://github.com/obra/superpowers) skills
+6. Deploy Comet skills (in your chosen language) to selected platforms
+7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
 
 ## Commands
 

package/assets/manifest.json

@@ -1,15 +1,19 @@
-{
-  "version": "0.1.0",
-  "skills": [
-    "comet/SKILL.md",
-    "comet/scripts/comet-guard.sh",
-    "comet/scripts/comet-yaml-validate.sh",
-    "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/scripts/comet-guard.sh",
+    "comet/scripts/comet-yaml-validate.sh",
+    "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"
+  ],
+  "languages": [
+    { "id": "en", "name": "English", "skillsDir": "skills" },
+    { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }
+  ]
+}

package/assets/skills/comet/SKILL.md

@@ -1,204 +1,206 @@
----
-name: comet
-description: "Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。"
----
-
-# Comet — OpenSpec + Superpowers 双星开发流程
-
-OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。OpenSpec 负责 WHAT，Superpowers 负责 HOW。
-
-```
-OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
-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>
-
-## 阶段自动检测
-
-### Step 0: 活跃 Change 发现
-
-**立即执行：**
-
-1. 运行 `openspec list --json` 获取所有活跃 change
-2. 对每个 change，检查 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 匹配关联文件，判断阶段和进度
-
-**分支逻辑：**
-
-| 情况 | 行为 |
-|------|------|
-| 无活跃 change | → 调用 `/comet-open` |
-| 恰好 1 个活跃 change | → 自动选中，进入阶段判定（Step 1） |
-| 多个活跃 change | → 列出清单让用户选择 |
-
-**多 change 选择**：使用 AskUserQuestion 展示，格式示例：
-
-```
-| # | Change 名称 | 当前阶段 | 任务进度 |
-|---|------------|---------|---------|
-| 1 | xxx-feature | Build | 3/5 tasks |
-| 2 | yyy-fix | Design | No design doc |
-```
-
-用户选择后，对选中的 change 进入阶段判定。
-
-**Preset 检测**：
-- 如用户明确描述为 bug fix / 热修复，且满足 hotfix 适用条件，直接调用 `/comet-hotfix`（跳过选择）。
-- 如用户明确描述为文案、配置、文档、prompt 或小范围非 bug 调整，且满足 tweak 适用条件，直接调用 `/comet-tweak`（跳过选择）。
-
-### Step 1: Comet 状态元数据读取
-
-优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
-
-推荐元数据结构：
-
-```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
-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` | 已选择的执行方式，可为空 |
-| `verify_mode` | `light` 或 `full`，可为空 |
-| `verify_result` | `pending`、`pass` 或 `fail` |
-| `verified_at` | 验证通过时间，可为空 |
-| `archived` | change 是否已归档 |
-
-### Step 2: 阶段判定
-
-对选中的 change，按以下顺序判断当前状态：
-
-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`
-
-如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
-
----
-
-## 子命令
-
-| 命令 | 阶段 | 归属 | 产物 |
-|------|------|------|------|
-| `/comet-open` | 1. 开启 | OpenSpec | proposal.md、design.md、tasks.md |
-| `/comet-design` | 2. 深度设计 | Superpowers | Design Doc、delta spec |
-| `/comet-build` | 3. 计划与构建 | Superpowers | 实施计划、代码提交 |
-| `/comet-verify` | 4. 验证与收尾 | Both | 验证报告、分支处理 |
-| `/comet-archive` | 5. 归档 | OpenSpec | delta→main spec 同步、design doc 标注、归档 |
-| `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
-| `/comet-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
-
----
-
-## 流程图
-
-```
-/comet
-  ↓ 自动检测
-/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
-  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
-
-/comet-hotfix（预设路径，跳过 brainstorming）
-  open ──→ build ──→ verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
-
-/comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
-  open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
-```
-
----
-
-## 错误处理
-
-| 场景 | 处理方式 |
-|------|---------|
-| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
-| 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
-| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
-| change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
-
----
-
-## 快速参考
-
-### 脚本定位
-
-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`。
-
-### 文件结构
-
-```
-openspec/                              # OpenSpec — WHAT
-├── config.yaml
-├── changes/
-│   ├── <name>/                        # 活跃 change
-│   │   ├── .openspec.yaml
-│   │   ├── .comet.yaml
-│   │   ├── proposal.md                # Why + What
-│   │   ├── design.md                  # 高层架构决策
-│   │   ├── specs/<capability>/spec.md # Delta 能力规格
-│   │   └── tasks.md                   # 任务清单
-│   └── archive/YYYY-MM-DD-<name>/     # 已归档
-└── specs/<capability>/spec.md         # 主 specs（归档时从 delta 同步）
-
-docs/superpowers/                      # Superpowers — HOW
-├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标注状态）
-└── plans/YYYY-MM-DD-<feature>.md      # 实施计划（文件头含 change 关联元数据）
-```
-
-### 最佳实践
-
-1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
-2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
-3. **保持 tasks.md 同步** — 完成一个勾一个
-4. **频繁提交** — 每个任务一次提交，message 体现设计意图
-5. **先验证再归档** — `/comet-verify` 通过后才执行 `/comet-archive`
-6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
-7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
-8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
-9. **增量修改已有功能** — 基于 main spec 创建 delta spec 基线，不从零编写
-10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程
+---
+name: comet
+description: "Comet — OpenSpec + Superpowers dual-star development workflow. Start with /comet for automatic phase detection and dispatch to subcommands. Five phases: open → design → build → verify → archive."
+---
+
+# Comet — OpenSpec + Superpowers Dual-Star Development Workflow
+
+OpenSpec and Superpowers orbit the same goal like a binary star system. OpenSpec handles WHAT, Superpowers handles HOW.
+
+```
+OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
+Superpowers handles HOW — technical design, planning, execution, closing
+```
+
+**Core principle: brainstorming cannot be skipped. Every change must undergo deep design (except hotfix and tweak presets).**
+
+<IMPORTANT>
+## Phase Transitions
+
+A single `/comet` invocation starts from the detected phase and prompts or advances to the next phase when exit conditions are met.
+
+Flow chain: open → design → build → verify → archive
+
+Nodes requiring user participation:
+1. Confirm design approach during brainstorming
+2. Select execution mode during build phase
+3. Decide to fix or accept deviation when verify fails
+4. Choose branch handling method for finishing-branch
+5. Encounter upgrade conditions (hotfix/tweak → full workflow)
+
+Agents should not skip these decision points; other unambiguous phase transitions can proceed automatically.
+</IMPORTANT>
+
+## Automatic Phase Detection
+
+### Step 0: Active Change Discovery
+
+**Execute immediately:**
+
+1. Run `openspec list --json` to get all active changes
+2. For each change, check `docs/superpowers/specs/` and `docs/superpowers/plans/` for associated files to determine phase and progress
+
+**Branch logic:**
+
+| Situation | Action |
+|-----------|--------|
+| No active change | → Invoke `/comet-open` |
+| Exactly 1 active change | → Auto-select, enter phase determination (Step 1) |
+| Multiple active changes | → List for user selection |
+
+**Multi-change selection**: Display using AskUserQuestion, example format:
+
+```
+| # | Change Name | Current Phase | Task Progress |
+|---|-------------|---------------|---------------|
+| 1 | xxx-feature | Build | 3/5 tasks |
+| 2 | yyy-fix | Design | No design doc |
+```
+
+After user selection, enter phase determination for the selected change.
+
+**Preset detection**:
+- If user explicitly describes as bug fix / hotfix and hotfix conditions are met, directly invoke `/comet-hotfix` (skip selection).
+- If user explicitly describes as copy, config, docs, prompt, or small non-bug adjustment and tweak conditions are met, directly invoke `/comet-tweak` (skip selection).
+
+### Step 1: Comet State Metadata Reading
+
+Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall back to `openspec status --change "<name>" --json`, `tasks.md`, and `docs/superpowers/` file checks.
+
+Recommended metadata structure:
+
+```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
+```
+
+Field meanings:
+
+| Field | Meaning |
+|-------|---------|
+| `workflow` | `full`, `hotfix`, or `tweak` |
+| `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` |
+| `design_doc` | Associated Superpowers Design Doc path, can be empty |
+| `plan` | Associated Superpowers Plan path, can be empty |
+| `build_mode` | Selected execution mode, can be empty |
+| `isolation` | `branch` or `worktree`, workspace isolation method, defaults to `branch` |
+| `verify_mode` | `light` or `full`, can be empty |
+| `verify_result` | `pending`, `pass`, or `fail` |
+| `verified_at` | Verification pass time, can be empty |
+| `archived` | Whether change is archived |
+
+### Step 2: Phase Determination
+
+For the selected change, determine current state in the following order:
+
+1. **`archived: true` or change moved to archive** → Workflow complete
+2. **`verify_result: pass` and `archived` is not `true`** → Invoke `/comet-archive`
+3. **`phase: verify` or tasks.md all checked** → Invoke `/comet-verify`
+4. **`phase: build` or has Design Doc but plan/execution incomplete** → Invoke `/comet-build`
+5. **`phase: design` or has change but no Design Doc** → Invoke `/comet-design`
+6. **No active change or state undeterminable** → Invoke `/comet-open`
+
+If metadata conflicts with file state, use verifiable file state as source of truth and correct `.comet.yaml` before continuing phase.
+
+---
+
+## Subcommands
+
+| Command | Phase | Owner | Artifacts |
+|---------|-------|-------|-----------|
+| `/comet-open` | 1. Open | OpenSpec | proposal.md、design.md、tasks.md |
+| `/comet-design` | 2. Deep Design | Superpowers | Design Doc、delta spec |
+| `/comet-build` | 3. Plan & Build | Superpowers | Implementation plan、code commits |
+| `/comet-verify` | 4. Verify & Close | Both | Verification report、branch handling |
+| `/comet-archive` | 5. Archive | OpenSpec | delta→main spec sync、design doc markup、archive |
+| `/comet-hotfix` | Preset path | Both | Quick fix (skip brainstorming) |
+| `/comet-tweak` | Preset path | Both | Small change (skip brainstorming and full plan) |
+
+---
+
+## Flow Diagram
+
+```
+/comet
+  ↓ Auto-detect
+/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/comet-hotfix（preset path, skip brainstorming）
+  open ──→ build ──→ verify ──→ archive
+    ↑ If upgrade triggered → supplement Design Doc → return to full workflow
+
+/comet-tweak（preset path, skip brainstorming and full plan）
+  open ──→ lightweight build ──→ light verify ──→ archive
+    ↑ If upgrade triggered → supplement Design Doc → return to full workflow
+```
+
+---
+
+## Error Handling
+
+| Scenario | Handling |
+|----------|----------|
+| `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
+| Sub-skill unavailable (e.g., `superpowers:brainstorming`) | Stop workflow, prompt to install or enable corresponding skill |
+| `.comet.yaml` malformed or missing | Use file state as source of truth (tasks.md、docs/superpowers/), correct metadata then continue |
+| Maven compile/test fails | Return to build phase for fixes, do not enter verify |
+| Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
+
+---
+
+## Quick Reference
+
+### Script Location
+
+Comet phase guard script `comet-guard.sh` is distributed with the skill package, located in `comet/scripts/` directory.
+**Do not hardcode platform paths**, self-locate at runtime with:
+
+```bash
+COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
+bash "$COMET_GUARD" <change-name> <phase>
+```
+
+In subsequent documentation, `bash $COMET_GUARD <change> <phase>` refers to this command. After loading comet, agents should cache `COMET_GUARD` path in shell environment to avoid repeated `find`.
+
+### File Structure
+
+```
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # Active change
+│   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # High-level architecture decisions
+│   │   ├── specs/<capability>/spec.md # Delta capability spec
+│   │   └── tasks.md                   # Task checklist
+│   └── archive/YYYY-MM-DD-<name>/     # Archived
+└── specs/<capability>/spec.md         # Main specs (sync from delta at archive)
+
+docs/superpowers/                      # Superpowers — HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # Design doc (technical RFC, mark status at archive)
+└── plans/YYYY-MM-DD-<feature>.md      # Implementation plan (file header contains change association metadata)
+```
+
+### Best Practices
+
+1. **brainstorming cannot be skipped** — Every change must undergo deep design (except hotfix and tweak)
+2. **delta spec is a living document** — Freely modify during phase 3, sync at archive
+3. **Keep tasks.md in sync** — Check off each completed task
+4. **Commit frequently** — One commit per task, message reflects design intent
+5. **Verify before archive** — Execute `/comet-archive` only after `/comet-verify` passes
+6. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
+7. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
+8. **Archive closure** — design doc and plan must mark `archived-with` status
+9. **Incremental modification of existing features** — Create delta spec baseline based on main spec, not from scratch
+10. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions

package/assets/skills/comet/scripts/comet-yaml-validate.sh

@@ -49,7 +49,7 @@ warn_msg() { warn "  WARN: $1"; WARNINGS=$((WARNINGS + 1)); }
 echo "[VALIDATE] $YAML" >&2
 
 # --- Required fields ---
-REQUIRED_FIELDS="workflow phase design_doc plan build_mode verify_mode verify_result verified_at archived"
+REQUIRED_FIELDS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verified_at archived"
 for field in $REQUIRED_FIELDS; do
   if ! grep -q "^${field}:" "$YAML" 2>/dev/null; then
     fail "missing required field '$field'"
@@ -78,6 +78,7 @@ validate_enum() {
 workflow=$(field_value "workflow")
 phase=$(field_value "phase")
 build_mode=$(field_value "build_mode")
+isolation=$(field_value "isolation")
 verify_mode=$(field_value "verify_mode")
 verify_result=$(field_value "verify_result")
 archived=$(field_value "archived")
@@ -87,6 +88,7 @@ plan=$(field_value "plan")
 validate_enum "workflow"      "$workflow"      "full hotfix tweak"
 validate_enum "phase"         "$phase"          "design build verify archive"
 validate_enum "build_mode"    "$build_mode"     "subagent-driven-development executing-plans direct"
+validate_enum "isolation"     "$isolation"      "branch worktree"
 validate_enum "verify_mode"   "$verify_mode"    "light full"
 validate_enum "verify_result" "$verify_result"  "pending pass fail"
 validate_enum "archived"      "$archived"       "true false"
@@ -106,7 +108,7 @@ if [ -n "$plan" ] && [ "$plan" != "null" ]; then
 fi
 
 # --- Unknown keys check ---
-KNOWN_KEYS="workflow phase design_doc plan build_mode verify_mode verify_result verified_at archived"
+KNOWN_KEYS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verified_at archived"
 while IFS=: read -r key _; do
   key="${key// /}"
   [ -z "$key" ] && continue