@house365/comate 0.10.0 → 0.10.2

package/skills/comate/reference/prerequisites.md

@@ -1,89 +1,89 @@
-# 前置依赖检查清单（prerequisites）
-
-规范路径：`comate/reference/prerequisites.md`
-
-`comate init` 会自动装好 OpenSpec CLI、Superpowers 和 comate 自身，正常情况下不需要手动执行本清单。清单保留下来用于排查：init 报某项失败时，对照这里确认要装什么、怎么自查、怎么补。
-
-> 一键自查：`comate doctor`（或直接 `bash comate/scripts/comate.sh doctor`）。它会检查下列大部分项目并给出可执行提示。
-
-## 1. 运行环境
-
-| 依赖 | 要求 | 检查 | 缺失处理 |
-|------|------|------|----------|
+# 前置依赖检查清单（prerequisites）
+
+规范路径：`comate/reference/prerequisites.md`
+
+`comate init` 会自动装好 OpenSpec CLI、Superpowers 和 comate 自身，正常情况下不需要手动执行本清单。清单保留下来用于排查：init 报某项失败时，对照这里确认要装什么、怎么自查、怎么补。
+
+> 一键自查：`comate doctor`（或直接 `bash comate/scripts/comate.sh doctor`）。它会检查下列大部分项目并给出可执行提示。
+
+## 1. 运行环境
+
+| 依赖 | 要求 | 检查 | 缺失处理 |
+|------|------|------|----------|
 | bash | ≥ 3.2 | `bash --version` | Windows 用 Git Bash / WSL；macOS 自带 3.2 可直接使用 |
-| git | 任意近代版本 | `git --version` | 安装 git |
-| sha256 工具 | `sha256sum` 或 `shasum` 至少其一 | `command -v sha256sum shasum` | Linux 装 coreutils；macOS 自带 `shasum`（perl） |
-| LF 换行 | 所有 `.sh` 必须是 LF | `doctor` 会检测 CRLF | 仓库已带 `.gitattributes` 强制 `eol=lf`；若被改坏，用 `dos2unix` 或重新 checkout |
-
-## 2. OpenSpec（WHAT 侧）
-
-负责 proposal / spec 生命周期 / 归档。comate 的 open / archive 阶段依赖它。
-
-安装：
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-初始化（在项目根目录）。`comate init` 已经做过这一步，手动补做时需要 `--tools`：openspec 靠探测已有的 agent 配置目录决定写哪些 tool 文件，干净项目里探测不到会直接报 `No tools detected` 退出。
-
-```bash
-openspec init . --tools none
-```
-
-自查：
-
-```bash
-openspec --version
-openspec list --json    # 列出活跃 change，应能正常返回
-```
-
-comate 用到的 OpenSpec 能力（以 skill 形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。确认这些 skill 在你的平台 skills 目录中可用。
-
-## 3. Superpowers（HOW 侧）
-
-负责技术设计 / 计划 / 执行 / 收尾。comate 的 design / build / verify 阶段依赖它。
-
-`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。安装后确认下列 skill 可加载：
-
-- `superpowers:brainstorming`
-- `superpowers:writing-plans`
-- `superpowers:subagent-driven-development`
-- `superpowers:executing-plans`
-- `superpowers:test-driven-development`
-- `superpowers:using-git-worktrees`
-- `superpowers:finishing-a-development-branch`
-
-自查：在 agent 中尝试加载 `superpowers:brainstorming`。若不可用，按你平台的安装说明补装。**任一 Superpowers 步骤不可用时，对应阶段必须停止并提示安装，不得用普通对话替代该步骤。**
-
-## 4. comate 自身
-
-comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
-
-采用**平铺布局**——每个 phase 是顶层 skill 目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，平铺是共同可用的最小公倍数：
-
-```
-skills/
-├── comate/                 # 主入口 + 共享资源
-│   ├── SKILL.md            #   /comate：探测并分派
-│   ├── reference/
-│   │   ├── dirty-worktree.md
-│   │   ├── decision-points.md
-│   │   └── prerequisites.md
-│   ├── scripts/
-│   │   ├── comate-lib.sh
-│   │   └── comate.sh
-│   └── tests/
-│       ├── comate.bats
-│       └── run.sh
-├── comate-open/SKILL.md    # 阶段 1
-├── comate-design/SKILL.md  # 阶段 2
-├── comate-build/SKILL.md   # 阶段 3
-├── comate-verify/SKILL.md  # 阶段 4
-├── comate-archive/SKILL.md # 阶段 5
-├── comate-fix/SKILL.md     # 预设(bug + 调整)
-```
-
-各 phase skill 通过 `*/comate/scripts/comate.sh` glob 定位脚本，共享 `comate/reference/*` 和 `comate/scripts/*`。若目标平台支持嵌套 skill 发现，也可改回 `comate/<phase>/SKILL.md` 子目录布局，纯命名调整，不影响脚本。
-
-`doctor` 会校验 `comate/scripts/` 下文件齐全且为 LF。
+| git | 任意近代版本 | `git --version` | 安装 git |
+| sha256 工具 | `sha256sum` 或 `shasum` 至少其一 | `command -v sha256sum shasum` | Linux 装 coreutils；macOS 自带 `shasum`（perl） |
+| LF 换行 | 所有 `.sh` 必须是 LF | `doctor` 会检测 CRLF | 仓库已带 `.gitattributes` 强制 `eol=lf`；若被改坏，用 `dos2unix` 或重新 checkout |
+
+## 2. OpenSpec（WHAT 侧）
+
+负责 proposal / spec 生命周期 / 归档。comate 的 open / archive 阶段依赖它。
+
+安装：
+
+```bash
+npm install -g @fission-ai/openspec@latest
+```
+
+初始化（在项目根目录）。`comate init` 已经做过这一步，手动补做时需要 `--tools`：openspec 靠探测已有的 agent 配置目录决定写哪些 tool 文件，干净项目里探测不到会直接报 `No tools detected` 退出。
+
+```bash
+openspec init . --tools none
+```
+
+自查：
+
+```bash
+openspec --version
+openspec list --json    # 列出活跃 change，应能正常返回
+```
+
+comate 用到的 OpenSpec 能力（以 skill 形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。确认这些 skill 在你的平台 skills 目录中可用。
+
+## 3. Superpowers（HOW 侧）
+
+负责技术设计 / 计划 / 执行 / 收尾。comate 的 design / build / verify 阶段依赖它。
+
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。安装后确认下列 skill 可加载：
+
+- `superpowers:brainstorming`
+- `superpowers:writing-plans`
+- `superpowers:subagent-driven-development`
+- `superpowers:executing-plans`
+- `superpowers:test-driven-development`
+- `superpowers:using-git-worktrees`
+- `superpowers:finishing-a-development-branch`
+
+自查：在 agent 中尝试加载 `superpowers:brainstorming`。若不可用，按你平台的安装说明补装。**任一 Superpowers 步骤不可用时，对应阶段必须停止并提示安装，不得用普通对话替代该步骤。**
+
+## 4. comate 自身
+
+comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+
+采用**平铺布局**——每个 phase 是顶层 skill 目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，平铺是共同可用的最小公倍数：
+
+```
+skills/
+├── comate/                 # 主入口 + 共享资源
+│   ├── SKILL.md            #   /comate：探测并分派
+│   ├── reference/
+│   │   ├── dirty-worktree.md
+│   │   ├── decision-points.md
+│   │   └── prerequisites.md
+│   ├── scripts/
+│   │   ├── comate-lib.sh
+│   │   └── comate.sh
+│   └── tests/
+│       ├── comate.bats
+│       └── run.sh
+├── comate-open/SKILL.md    # 阶段 1
+├── comate-design/SKILL.md  # 阶段 2
+├── comate-build/SKILL.md   # 阶段 3
+├── comate-verify/SKILL.md  # 阶段 4
+├── comate-archive/SKILL.md # 阶段 5
+├── comate-fix/SKILL.md     # 预设(bug + 调整)
+```
+
+各 phase skill 通过 `*/comate/scripts/comate.sh` glob 定位脚本，共享 `comate/reference/*` 和 `comate/scripts/*`。若目标平台支持嵌套 skill 发现，也可改回 `comate/<phase>/SKILL.md` 子目录布局，纯命名调整，不影响脚本。
+
+`doctor` 会校验 `comate/scripts/` 下文件齐全且为 LF。

package/skills/comate-archive/SKILL.md

@@ -1,63 +1,63 @@
----
-name: comate-archive
-description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
----
-
-# comate 阶段 5：归档（Archive）
-
-## 前置条件
-
-- 验证已通过（阶段 4 完成），分支已处理
-- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
-
-## 步骤
-
-### 0. 入口状态验证
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
-  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
-done | head -1)}"
-if [ -z "$COMATE" ]; then
-  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
-  return 1 2>/dev/null || exit 1
-fi
-bash "$COMATE" state <name> check archive
-```
-
-### 1. 执行归档
-
-```bash
-bash "$COMATE" archive "<name>"
-```
-
-脚本自动完成：
-1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
-2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
-3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
-4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
-5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
-6. 通过 `state transition <archive-name> archived` 设 `archived: true`
-7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
-
-非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
-
-需预览不实际执行：加 `--dry-run`。
-
-### 2. 生命周期闭环
-
-```
-brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
-```
-
-## 退出条件
-
-- 归档脚本退出码 0
-- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
-- 归档后 `.comate.yaml` 中 `archived: true`
-
-归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
-
-## 完成
-
-comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。
+---
+name: comate-archive
+description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
+---
+
+# comate 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成），分支已处理
+- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 入口状态验证
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+bash "$COMATE" state <name> check archive
+```
+
+### 1. 执行归档
+
+```bash
+bash "$COMATE" archive "<name>"
+```
+
+脚本自动完成：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
+3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
+4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
+5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
+6. 通过 `state transition <archive-name> archived` 设 `archived: true`
+7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
+
+非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
+
+需预览不实际执行：加 `--dry-run`。
+
+### 2. 生命周期闭环
+
+```
+brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本退出码 0
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
+- 归档后 `.comate.yaml` 中 `archived: true`
+
+归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
+
+## 完成
+
+comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。