@rpamis/comet 0.1.2 → 0.1.3

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,184 +1,236 @@
-# @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
+# @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) |
+
+### Guard Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `comet-guard.sh` | Phase transition guard — validates exit conditions before phase transitions |
+| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
+
+### 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`
+
+### State Management
+
+Comet uses a decoupled state architecture with separate YAML files:
+
+| File | Owner | Purpose |
+|------|-------|---------|
+| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
+| `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
+
+**Key Fields in `.comet.yaml`:**
+- `workflow`: `full`, `hotfix`, or `tweak`
+- `phase`: `design`, `build`, `verify`, `archive`
+- `design_doc`: Path to Superpowers Design Doc
+- `plan`: Path to implementation plan
+- `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
+- `verify_mode`: `light` or `full`
+- `verify_result`: `pending`, `pass`, or `fail`
+- `archived`: Boolean indicating if change is archived
+
+### Reliability Features
+
+Comet includes three-layer defense to ensure agent execution reliability:
+
+1. **Entry Verification** — Each phase validates preconditions before execution
+   - Checks file existence, state consistency, and phase transitions
+   - Outputs `[HARD STOP]` with actionable suggestions if validation fails
+
+2. **Write-Then-Verify** — Every state write is immediately verified
+   - After updating `.comet.yaml`, agents must verify field values
+   - Automatic retry mechanism (up to 2 attempts) on mismatch
+
+3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
+   - Validates required fields (9 fields)
+   - Validates enum values (6 enum types)
+   - Validates referenced file paths exist
+   - Detects unknown/typos fields
+
+**Security**: Path traversal protection on all change name inputs
+
+## Project Structure
+
+```
+your-project/
+├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
+│   ├── comet/SKILL.md
+│   │   └── scripts/
+│   │       ├── comet-guard.sh       # Phase transition guard
+│   │       └── comet-yaml-validate.sh # Schema validator
+│   ├── comet-*/SKILL.md
+│   ├── openspec-*/SKILL.md
+│   └── brainstorming/SKILL.md
+├── openspec/                    # OpenSpec — WHAT
+│   ├── config.yaml
+│   └── changes/
+│       └── <name>/
+│           ├── .openspec.yaml       # OpenSpec state
+│           ├── .comet.yaml          # Comet workflow state (decoupled)
+│           ├── 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
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+
+## 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

@@ -2,6 +2,8 @@
   "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",

package/assets/skills/comet/SKILL.md

@@ -65,21 +65,20 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以
 
 ### Step 1: Comet 状态元数据读取
 
-优先读取 `openspec/changes/<name>/.openspec.yaml` 中的 `comet` 元数据。若该字段不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
 
 推荐元数据结构：
 
 ```yaml
-comet:
-  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
+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
 ```
 
 字段含义：
@@ -100,14 +99,14 @@ comet:
 
 对选中的 change，按以下顺序判断当前状态：
 
-1. **`comet.archived: true` 或 change 已移入 archive** → 流程已完成
-2. **`comet.verify_result: pass` 且 `comet.archived` 不是 `true`** → 调用 `/comet-archive`
-3. **`comet.phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
-4. **`comet.phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
-5. **`comet.phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
+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.yaml` 中的 `comet` 字段。
+如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
 
 ---
 
@@ -150,7 +149,7 @@ comet:
 |------|---------|
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
 | 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
-| `.openspec.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
 | Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
 
@@ -178,6 +177,7 @@ openspec/                              # OpenSpec — WHAT
 ├── changes/
 │   ├── <name>/                        # 活跃 change
 │   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
 │   │   ├── proposal.md                # Why + What
 │   │   ├── design.md                  # 高层架构决策
 │   │   ├── specs/<capability>/spec.md # Delta 能力规格