@house365/comate 0.1.0

package/skills/comate/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: comate
+description: "comate —— OpenSpec + Superpowers 规格驱动开发编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
+---
+
+# comate —— OpenSpec + Superpowers 规格驱动开发流
+
+
+**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
+
+---
+
+## 决策核心
+
+agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
+
+### 自动阶段探测
+
+**Step 0：活跃 change 发现 + 意图探测**
+
+1. 先探测预设；命中 hotfix/tweak 条件则直接调用对应预设 skill，不进入普通 open 分支。
+2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
+
+**预设探测优先级最高**：
+- 用户明确描述 bug 修复/热修 + 满足 hotfix 条件 → 直接调用 `/comate-hotfix`
+- 用户明确描述文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接调用 `/comate-tweak`
+- 无预设命中 → 按下表处理
+
+| 活跃 change | 用户输入 | 行为 |
+|-------------|----------|------|
+| 无 | 非预设输入 | → 调用 `/comate-open` |
+| 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
+| 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
+| 恰好 1 个 | `/comate` 无描述 | → 自动选中，进入 Step 1 |
+| 多个 | `/comate` 无描述 | → 列出 change 供用户选择 |
+
+<IMPORTANT>
+用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
+`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
+直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
+</IMPORTANT>
+
+**Step 1：读取 `.comate.yaml` 状态元数据**
+
+优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
+
+**断点恢复规则**：
+- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
+- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
+- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点（决策点 4）：暂停询问修复或接受偏差；仅在用户选修复后运行 `state transition <name> verify-fail` 并调用 `/comate-build`。
+- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
+- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
+
+**Step 2：阶段判定**（按顺序检查，首个命中者生效）
+
+1. `archived: true` 或 change 已移入 archive → 流程完成
+2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
+3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
+4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
+5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`hotfix`→`/comate-hotfix`，`tweak`→`/comate-tweak`，`full`→`/comate-build`
+6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
+7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
+8. 无活跃 change → 调用 `/comate-open`
+
+元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
+
+### 预设升级判定
+
+**hotfix → full**（任一满足即升级）：改动 ≥ 3 文件 / 架构变更（新模块、新接口、新依赖）/ 数据库 schema 变更 / 引入新 public API / 范围超出单一函数模块。
+
+**tweak → full**（任一满足即升级）：改动 ≥ 5 文件 / 跨模块协调 / 需新增 ≥ 5 测试用例 / 配置项增删（非值修改）。
+
+### 错误处理速查
+
+| 场景 | 处理 |
+|------|------|
+| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
+| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
+| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
+
+### 阶段流转
+
+<IMPORTANT>
+一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
+
+流转链：open → design → build → verify → archive
+
+**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
+
+7 个决策阻塞点 + Red Flags 表见 `comate/reference/decision-points.md`。到达任一决策点必须停下用 AskUserQuestion 等待用户选择；其他无歧义流转自动进行，不得中途退出。
+</IMPORTANT>
+
+---
+
+## 子命令速查
+
+| 命令 | 阶段 | Owner | 产物 |
+|------|------|-------|------|
+| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
+| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
+| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
+| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
+| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
+| `/comate-hotfix` | 预设 | 双方 | 快速修复（跳过 brainstorming） |
+| `/comate-tweak` | 预设 | 双方 | 小调整（跳过 brainstorming + 完整 plan） |
+
+```
+/comate
+  ↓ 自动探测
+/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
+  (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
+```
+
+---
+
+## 参考附录
+
+### 脚本定位（单一入口）
+
+comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/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
+```
+
+之后全程复用 `$COMATE`：
+
+```bash
+bash "$COMATE" state   <name> init <full|hotfix|tweak>
+bash "$COMATE" state   <name> transition <event>
+bash "$COMATE" state   <name> check <phase> [--json]
+bash "$COMATE" state   <name> recover <phase>
+bash "$COMATE" state   <name> scale
+bash "$COMATE" state   <name> validate
+bash "$COMATE" guard   <name> <phase> [--apply] [--json]
+bash "$COMATE" handoff <name> <design|build> --write [--full]
+bash "$COMATE" sources <name> track <file...> [--note <text>]
+bash "$COMATE" sources <name> check | list
+bash "$COMATE" sources find <file>
+bash "$COMATE" archive <name> [--dry-run]
+bash "$COMATE" status
+bash "$COMATE" doctor
+```
+
+`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
+
+### `.comate.yaml` 字段参考
+
+状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
+
+| 字段 | 含义 |
+|------|------|
+| `schema_version` | 状态文件格式版本（当前 1） |
+| `workflow` | `full` / `hotfix` / `tweak` |
+| `phase` | `open` / `design` / `build` / `verify` / `archive` |
+| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
+| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；hotfix/tweak 默认 `direct`） |
+| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
+| `verify_mode` | `light` / `full`（由 scale 评估写入） |
+| `verify_result` | `pending` / `pass` / `fail` |
+| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
+| `branch_status` | `pending` / `handled` |
+| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
+| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
+| `direct_override` | full 流程用 `direct` 需显式 `true` |
+| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
+| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
+| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
+
+状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
+- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
+- `build → verify` 前 `build_mode` 必须已选
+- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
+- `build_mode: direct` 默认仅 hotfix/tweak；full 流程需 `direct_override: true`
+- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec —— WHAT
+├── changes/<name>/
+│   ├── .comate.yaml                   # comate 状态机真相源
+│   ├── proposal.md / design.md / tasks.md
+│   ├── specs/<capability>/spec.md     # delta 能力规格
+│   └── .comate/handoff/               # 脚本生成的阶段交接包
+│       └── ../sources.manifest        # 知识库源文件清单（source_kind=file 时）
+└── specs/<capability>/spec.md         # 主 spec（归档时由 delta 覆盖）
+
+docs/knowledge-base/<...>.md           # 可追踪的需求源文档（source_kind=file）
+
+docs/superpowers/                      # Superpowers —— HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
+├── plans/YYYY-MM-DD-<feature>.md      # 实施计划
+└── reports/                           # 验证报告
+```
+
+### 最佳实践
+
+1. brainstorming 不可跳过（hotfix/tweak 除外）
+2. delta spec 是活文档，build 阶段随时改，归档时同步
+3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
+4. tasks.md 实时同步，每完成一个任务勾选并提交
+5. 验证通过才归档
+6. 预设有边界，命中升级条件及时转 full

package/skills/comate/reference/decision-points.md

@@ -0,0 +1,54 @@
+# 决策阻塞点清单（decision-points）
+
+规范路径：`comate/reference/decision-points.md`（单一真相源）
+
+本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
+
+## 通用规则
+
+**决策点是阻塞点**。到达下列任一节点时，当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
+
+- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
+- 不得用推荐规则、默认值或历史偏好替代用户确认。
+- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
+- 其他无歧义的阶段流转必须自动进行，不得中途退出。
+
+## 七个决策点
+
+1. **开题产物审视确认**（open）
+   proposal/design/tasks 三件套完成且内容完整后，暂停请用户确认或要求调整。
+   引用：`comate-open` 退出条件。
+
+2. **设计方案确认**（design / brainstorming）
+   brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
+   引用：`comate-design` Step 1c。
+
+3. **构建工作方式选择**（build）
+   开始执行前，**一次性**询问工作区隔离方式（branch / worktree）、执行方式（subagent-driven-development / executing-plans）和 TDD 模式（tdd / direct）。一次交互内取得三项选择，并分别写入 `isolation`、`build_mode`、`tdd_mode`。
+   引用：`comate-build` Step 3。
+
+4. **验证失败决策**（verify）
+   验证不通过时，暂停请用户决定全部修复 / 逐项处理 / 接受偏差。含 Spec 漂移处理（design doc 与 delta spec 矛盾）。CRITICAL 失败项必须修复。用户选择修复后才执行 `state transition <name> verify-fail` 并回到 build。
+   引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
+
+5. **分支收尾方式选择**（verify / finishing-a-development-branch）
+   暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
+   引用：`comate-verify` Step 3。
+
+6. **预设升级确认**（hotfix / tweak → full）
+   命中升级条件（见各 preset SKILL 的「升级条件」表）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
+   引用：`comate-hotfix` / `comate-tweak`「升级条件」。
+
+7. **构建期范围扩张**（build）
+   实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
+   引用：`comate-build` Step 4。
+
+## Red Flags — 出现这些念头就停下来检查
+
+| Agent 的念头 | 实际风险 |
+|--------------|----------|
+| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
+| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
+| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
+| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
+| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |

package/skills/comate/reference/dirty-worktree.md

@@ -0,0 +1,58 @@
+# Dirty Worktree 协议
+
+规范路径：`comate/reference/dirty-worktree.md`
+
+本协议由所有涉及代码修改的 comate 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。
+
+## 1. 检查步骤
+
+继续或开始修改前，必须先运行以下命令：
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。
+
+## 2. 核心规则
+
+- 用户可能不会说明自己改了哪里。只要存在 dirty worktree（包括 Git 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源。
+- dirty worktree 只代表代码事实，不会自动推进 `.comate.yaml` 的 `phase` 或勾选 `tasks.md`；只有完成归因、验证、同步必要文档，并通过对应阶段 guard 后，才允许推进 comate 状态。
+
+## 3. 归因分类
+
+将 dirty diff 分为三类：
+
+1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。纳入当前任务继续，不重复改同一处。
+2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃。
+3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段。
+
+## 4. 常见处理模式
+
+### 已实现但 tasks.md 未勾选
+
+先验证实现（运行构建和测试），通过后补勾任务。不要因为任务未勾选就重做一遍，也不要因为状态文件滞后而忽略代码事实。若当前子 skill 定义了阶段特例，以子 skill 为准。
+
+### 暗示计划或范围已变化
+
+按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。
+
+### 模糊恢复意图
+
+用户说“继续”“接着跑”“我改了一点”“刚才不满意”“重新弄”“代码动过”“先按现在的来”等模糊恢复意图时，按本协议处理。不要要求用户先回忆具体改了哪里。
+
+### open/design 阶段出现代码改动
+
+若当前仍处于 `open` 或 `design`，但 dirty worktree 已经包含代码改动，先按本协议归因，不要直接推进阶段：
+
+- 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard。
+- 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃。
+- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify。
+
+## 5. 禁令
+
+- 禁止在未理解 dirty diff 来源时覆盖、回滚、格式化重写或忽略用户改动。
+- 禁止在 dirty diff 未解释清楚时判定验证通过。

package/skills/comate/reference/prerequisites.md

@@ -0,0 +1,88 @@
+# 前置依赖检查清单（prerequisites）
+
+规范路径：`comate/reference/prerequisites.md`
+
+comate 不附带安装器：OpenSpec 与 Superpowers 需要**手动安装**，comate 本身的分发方式就是「复制 `comate/` 文件夹」。本清单说明需要装什么、怎么自查、怎么补。
+
+> 一键自查：运行 `bash comate/scripts/comate.sh doctor`。它会检查下列大部分项目并给出可执行提示。
+
+## 1. 运行环境
+
+| 依赖 | 要求 | 检查 | 缺失处理 |
+|------|------|------|----------|
+| bash | ≥ 4（需要关联数组） | `bash --version` | Windows 用 Git Bash / WSL；macOS 自带 3.2，需 `brew install bash` |
+| 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
+```
+
+初始化（在项目根目录）：
+
+```bash
+openspec init
+```
+
+自查：
+
+```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 阶段依赖它。
+
+Superpowers 是一组 skill，按你所用平台的约定安装到 skills 目录（如 `.claude/skills/`、`.cursor/skills/`、`~/.config/skills/` 等）。安装后确认下列 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 的全部 skill 目录到目标平台的 skills 目录。本项目（Claude Code 插件）采用**平铺布局**，因为 Claude Code 只发现顶层 skill 目录：
+
+```
+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-hotfix/SKILL.md  # 预设
+└── comate-tweak/SKILL.md   # 预设
+```
+
+各 phase skill 通过 `*/comate/scripts/comate.sh` glob 定位脚本，共享 `comate/reference/*` 和 `comate/scripts/*`。若目标平台支持嵌套 skill 发现，也可改回 `comate/<phase>/SKILL.md` 子目录布局，纯命名调整，不影响脚本。
+
+`doctor` 会校验 `comate/scripts/` 下文件齐全且为 LF。