@rpamis/comet 0.1.2 → 0.1.3

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

@@ -11,6 +11,31 @@ description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec
 
 ## 步骤
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/` 目录已存在（由 openspec-new-change 创建）
+2. `openspec/changes/<name>/.comet.yaml` 文件不存在（尚未初始化）
+3. `openspec/changes/<name>/proposal.md` 存在且非空
+4. `openspec/changes/<name>/design.md` 存在且非空
+5. `openspec/changes/<name>/tasks.md` 存在且非空
+
+**验证方式：**
+- 读取以上路径确认存在/不存在
+- 如 `.comet.yaml` 已存在，读取其 `phase` 字段：如 phase 不为空，输出 `[HARD STOP]` 并提示可能已有活跃 change
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-open
+  Expected: .comet.yaml does not exist, proposal.md + design.md + tasks.md exist
+  Actual:   phase=<实际值>, design_doc=<实际值> (或文件不存在)
+  Suggestion: Check if another change with the same name is already active.
+```
+
+验证通过后才进入步骤 1。
+
 ### 1. 探索想法
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
@@ -19,13 +44,14 @@ description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec
 
 ### 2. 创建 Change 结构
 
-**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能（或 `openspec-propose` 如需先提建议）。
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需要先形成建议，改为加载 `openspec-propose`。禁止跳过此步骤。
 
 确认以下产物已创建：
 
 ```
 openspec/changes/<name>/
 ├── .openspec.yaml
+├── .comet.yaml
 ├── proposal.md       # Why + What：问题、目标、范围
 ├── design.md         # How（高层）：架构决策、方案选型
 └── tasks.md          # 任务清单（勾选框）
@@ -47,27 +73,37 @@ cp openspec/specs/<capability>/spec.md openspec/changes/<name>/specs/<capability
 ```
 
 3. 在复制的 delta spec 中，按 delta 格式组织变更（`## ADDED`、`## MODIFIED`、`## REMOVED`）
-4. 在 proposal.md 中注明 `基于已有 capability: <capability-name>` 
-
-**好处**：避免从零编写 delta spec，确保增量修改有完整上下文。
+4. 在 proposal.md 中注明 `基于已有 capability: <capability-name>`
 
 ### 3. 初始化 Comet 状态
 
-在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并以下元数据：
+在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
 
 ```yaml
-comet:
-  workflow: full
-  phase: design
-  design_doc: null
-  plan: null
-  build_mode: null
-  verify_mode: null
-  verify_result: pending
-  verified_at: null
-  archived: false
+workflow: full
+phase: design
+design_doc: null
+plan: null
+build_mode: null
+verify_mode: null
+verify_result: pending
+verified_at: null
+archived: false
 ```
 
+【写入验证】创建完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 workflow 行的值为 "full"
+  确认 phase 行的值为 "design"
+  确认 design_doc 行的值为 "null"
+  确认 plan 行的值为 "null"
+  确认 build_mode 行的值为 "null"
+  确认 verify_mode 行的值为 "null"
+  确认 verify_result 行的值为 "pending"
+  确认 verified_at 行的值为 "null"
+  确认 archived 行的值为 "false"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ### 4. 内容完整性检查
 
 确认三个文档内容完整：

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

@@ -21,6 +21,28 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ## 流程（preset workflow，4 阶段）
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/` 目录不存在，或目录存在但 `.comet.yaml` 不存在（无冲突）
+
+**验证方式：**
+- `test -d openspec/changes/<name>` 检查目录
+- 如目录存在，`test -f openspec/changes/<name>/.comet.yaml` 检查配置文件
+- 如 `.comet.yaml` 已存在，读取 `phase` 检查是否为未完成的 tweak
+
+**失败输出（有冲突）：**
+```
+[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=<实际值>
+  Suggestion: Pick a different change name, or check if an existing tweak is in progress.
+```
+
+验证通过后才进入流程步骤。
+
 执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
 
 ### 1. 快速开启（preset open）
@@ -35,21 +57,33 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
   - `tasks.md` — 不超过 3 个任务
 - **无需 delta spec**（除非变更改变了已有 spec 的验收场景；一旦需要 delta spec，升级为完整 `/comet`）
 
-在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并 tweak 状态：
+在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
 
 ```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
+workflow: tweak
+phase: build
+design_doc: null
+plan: null
+build_mode: direct
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
 ```
 
+【写入验证】创建完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 workflow 行的值为 "tweak"
+  确认 phase 行的值为 "build"
+  确认 design_doc 行的值为 "null"
+  确认 plan 行的值为 "null"
+  确认 build_mode 行的值为 "direct"
+  确认 verify_mode 行的值为 "light"
+  确认 verify_result 行的值为 "pending"
+  确认 verified_at 行的值为 "null"
+  确认 archived 行的值为 "false"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ### 2. 轻量构建（preset build）
 
 使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
@@ -73,11 +107,11 @@ comet:
 
 如规模评估进入完整验证路径，停止 tweak，升级为完整 `/comet`。
 
-验证通过后，按 `/comet-verify` 的规则将 `comet.verify_result` 记录为 `pass`，归档前不得跳过该状态。
+验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
 
 ### 4. 归档（preset archive）
 
-复用 `/comet-archive`。归档前必须满足 `comet.verify_result: pass`。
+复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`。
 
 **立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
 

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

@@ -12,6 +12,29 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 
 ## 步骤
 
+### 0. 入口状态验证（Entry Check）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+1. `openspec/changes/<name>/.comet.yaml` 存在
+2. `phase` 字段的值为 `"verify"`
+3. `verify_result` 字段为 `"pending"` 或 null（尚未验证通过）
+
+**验证方式：**
+- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
+- 如 `verify_result` 已是 `"pass"`，说明此 change 已验证过
+
+**失败输出：**
+```
+[HARD STOP] Entry check failed for comet-verify
+  Expected: phase=verify, verify_result=pending|null
+  Actual:   phase=<实际值>, verify_result=<实际值>
+  Suggestion: Run comet-build first, or this change was already verified.
+```
+
+验证通过后才进入步骤 1。
+
 ### 1. 改动规模评估
 
 根据以下指标判定改动规模：
@@ -25,7 +48,7 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 
 **判定规则**：任一指标命中"大" → 完整验证。全部命中"小" → 轻量验证。
 
-判定完成后，在 `openspec/changes/<name>/.openspec.yaml` 中记录实际验证模式。`verify_mode` 只允许以下值之一：
+判定完成后，在 `openspec/changes/<name>/.comet.yaml` 中记录实际验证模式。`verify_mode` 只允许以下值之一：
 
 - `light`
 - `full`
@@ -34,20 +57,23 @@ Few-shot 示例：
 
 ```yaml
 # 全部指标命中“小”
-comet:
-  phase: verify
-  verify_mode: light
-  verify_result: pending
+phase: verify
+verify_mode: light
+verify_result: pending
 ```
 
 ```yaml
-# 任一指标命中“大”
-comet:
-  phase: verify
-  verify_mode: full
-  verify_result: pending
+# 任一指标命中”大”
+phase: verify
+verify_mode: full
+verify_result: pending
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 verify_mode 行的值为 “<light 或 full>”
+  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ### 2a. 轻量验证（小改动）
 
 当规模评估结果为"小"时，跳过 `openspec-verify-change`，直接执行以下检查：
@@ -113,18 +139,24 @@ comet:
 
 - 验证报告通过
 - 分支已处理
-- `.openspec.yaml` 中 `comet.verify_result` 已记录为 `pass`
+- `.comet.yaml` 中 `verify_result` 已记录为 `pass`
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> verify`，全部 PASS 后才允许流转
 
-退出前合并更新：
+退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
 
 ```yaml
-comet:
-  phase: archive
-  verify_result: pass
-  verified_at: YYYY-MM-DD
+phase: archive
+verify_result: pass
+verified_at: YYYY-MM-DD
 ```
 
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "archive"
+  确认 verify_result 行的值为 "pass"
+  确认 verified_at 行的值非空（格式为 YYYY-MM-DD）
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
 ## 自动流转
 
 退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：

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,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",

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));