@house365/comate 0.10.2 → 1.0.2-next.0

package/docs/COMATE_INIT_DIRECTORY_GUIDE.md

@@ -1,201 +0,0 @@
-# comate init 目录说明
-
-`comate init` 会同时准备两类内容：用户级 skills，以及当前项目的 OpenSpec 和知识库目录。
-
-## 1. 初始化时会发生什么
-
-在项目根目录运行：
-
-```bash
-comate init
-```
-
-它会：
-
-- 将 comate、OpenSpec 和 Superpowers 相关 skills 安装到用户级 skills 目录。
-- 在当前项目创建 `openspec/`。
-- 在当前项目补齐 `docs/` 知识库骨架。
-- 保留已经存在的文件，不覆盖项目已有内容。
-
-项目目录通常会得到以下结构：
-
-```text
-your-project/
-├── openspec/
-│   ├── config.yaml
-│   ├── changes/
-│   │   └── archive/
-│   └── specs/
-└── docs/
-    ├── README.md
-    ├── architecture/
-    │   └── README.md
-    └── knowledge-base/
-        ├── README.md
-        ├── requirements/
-        │   └── _templates/
-        │       └── PRD.md
-        └── integrations/
-            ├── README.md
-            └── _TEMPLATE/
-                ├── README.md
-                └── api-snapshot.md
-```
-
-## 2. 用户级 skills
-
-默认目录：
-
-```text
-macOS/Linux: ~/.agents/skills/
-Windows:     %USERPROFILE%\.agents\skills\
-```
-
-这里保存可被多个项目共用的 skills。常见目录包括：
-
-| 目录 | 用途 |
-| --- | --- |
-| `comate/` | comate 总入口、状态脚本和共享规则 |
-| `comate-open/` | 创建 change，生成初始产物 |
-| `comate-design/` | 技术设计和方案确认 |
-| `comate-build/` | 计划和代码实现 |
-| `comate-verify/` | 测试、验证和分支收尾 |
-| `comate-archive/` | 归档 change 并同步规格 |
-| `comate-fix/` | Bug 或小调整的快速流程 |
-| `comate-gate/` | PRD 门禁和拆分 |
-| `comate-grill/` | 澄清关键决策 |
-| `comate-kb-integration/` | 生成第三方对接档案 |
-| `openspec-*/` | OpenSpec 提供的配套 skills |
-
-通常不需要手动修改这些目录。升级 comate 后，在项目根目录重新运行 `comate init`，即可同步新版 comate skills。
-
-## 3. 项目级 `openspec/`
-
-`openspec/` 保存当前项目的变更规格，是项目自己的文件，应纳入版本控制。
-
-### `openspec/config.yaml`
-
-OpenSpec 的项目配置文件，记录当前项目使用的规格 schema。通常由初始化命令创建；已有配置会保留，不要随意删除。
-
-### `openspec/changes/`
-
-每个进行中的需求或修复对应一个 change：
-
-```text
-openspec/changes/<change-name>/
-├── .comate.yaml
-├── proposal.md
-├── design.md
-├── tasks.md
-├── specs/<capability>/spec.md
-└── .comate/
-    ├── handoff/
-    └── sources.manifest
-```
-
-这些文件由 `/comate`、`/comate-fix` 及各阶段 skill 逐步生成：
-
-- `.comate.yaml`：comate 当前阶段和验证状态的事实来源。
-- `proposal.md`：为什么做、做什么、范围和非目标。
-- `design.md`：高层设计、方案选择和数据流。
-- `tasks.md`：实施任务清单，完成一项勾选一项。
-- `specs/<capability>/spec.md`：本次变更的增量能力规格。
-- `.comate/handoff/`：阶段之间自动生成的交接上下文。
-- `.comate/sources.manifest`：需求源文件的追踪清单，仅在需求来自文件时出现。
-
-`openspec/changes/archive/` 在初始化时就会创建。`<change-name>` 完成并归档后，会移动到：
-
-```text
-openspec/changes/archive/YYYY-MM-DD-<change-name>/
-```
-
-### `openspec/specs/`
-
-这里保存已经沉淀的长期能力规格：
-
-```text
-openspec/specs/<capability>/spec.md
-```
-
-归档 change 时，增量规格会合并到对应的主规格中。
-
-## 4. 项目级 `docs/`
-
-`docs/` 保存跨多个 change 长期有效的项目文档。初始化只创建骨架，具体内容需要项目团队补充。
-
-### `docs/README.md`
-
-说明 `docs/` 的整体边界，以及架构文档、知识库和 `openspec/` 的分工。一般不需要频繁修改。
-
-### `docs/architecture/`
-
-保存项目架构约束，例如：
-
-- 前后端分层和模块依赖；
-- API、DTO、数据库和错误码约定；
-- 命名、日志、测试和部署规范。
-
-初始化时只有占位说明。项目应根据实际技术栈补充正式规则。涉及架构约束的 PRD，门禁会以这里的内容作为对齐依据。
-
-### `docs/knowledge-base/`
-
-保存需求和第三方服务资料。
-
-#### `requirements/`
-
-存放原始 PRD。推荐按功能和日期组织：
-
-```text
-docs/knowledge-base/requirements/<YYYYMMDD-功能名>/
-├── PRD-001-功能名.md
-├── PRD-001.gate.yaml
-└── PRD-001-REVIEW.md
-```
-
-`_templates/PRD.md` 是新建 PRD 的模板。`.gate.yaml` 和 `-REVIEW.md` 由 `/comate-gate` 生成，不需要手动创建。
-
-#### `integrations/`
-
-保存第三方服务的长期对接档案：
-
-```text
-docs/knowledge-base/integrations/<service-id>/
-├── README.md
-└── api-snapshot.md
-```
-
-`_TEMPLATE/` 只存模板，不代表真实服务。接入新服务时，复制模板或使用 `/comate-kb-integration` 生成档案，并维护 `integrations/README.md` 中的服务索引。
-
-## 5. 后续流程会新增的目录
-
-以下目录不是 `comate init` 必然立即创建的，而是在对应阶段产生：
-
-```text
-docs/superpowers/
-├── specs/   # design 阶段的设计文档
-├── plans/   # build 阶段的实施计划
-└── reports/ # verify 阶段的验证报告
-```
-
-如果项目暂时没有进行中的 change，这些目录不存在是正常的。
-
-## 6. 哪些内容应提交到 Git
-
-建议提交项目级内容：
-
-- `openspec/`
-- `docs/architecture/`
-- `docs/knowledge-base/`
-- 已生成的 `docs/superpowers/`
-
-用户级 `~/.agents/skills/` 或 `%USERPROFILE%\.agents\skills\` 属于本机环境，不放进项目仓库。
-
-## 7. 重跑 init
-
-`comate init` 是幂等的：
-
-- 已安装的依赖和 skills 会跳过或复用；
-- 已存在的 `openspec/` 和 `docs/` 文件会保留；
-- 缺少的目录或模板文件会补齐。
-
-因此升级 comate 后，可以安全地在每个项目根目录重新运行一次 `comate init`。

package/docs/SUPERPOWERS_FIX_SUMMARY.md

@@ -1,114 +0,0 @@
-# Superpowers 重复安装问题修复总结
-
-## 问题描述
-
-在 v0.9.24 之前，`comate init` 无法检测 Claude Code plugin 安装的 superpowers，导致：
-- 即使 plugin 已安装，仍会通过 skills CLI 再次安装
-- 用户目录下出现重复的 superpowers 副本
-- 浪费磁盘空间和安装时间
-
-## 解决方案
-
-### 1. 预防重复安装（v0.9.24+）
-
-**修改文件：** `bin/init.mjs`
-
-扩展 `superpowersInstalled()` 函数，增加 plugin 检测：
-
-```javascript
-// 检查 skills CLI 安装（原有逻辑）
-if (roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))))) {
-  return true;
-}
-
-// 检查 Claude Code plugin 安装（新增逻辑）
-if (scope === 'global') {
-  const pluginRegistry = join(home, '.claude', 'plugins', 'installed_plugins.json');
-  try {
-    const registry = JSON.parse(readFileSync(pluginRegistry, 'utf8'));
-    return Object.keys(registry.plugins || {}).some((key) =>
-      key.startsWith('superpowers@') && 
-      Array.isArray(registry.plugins[key]) && 
-      registry.plugins[key].length > 0
-    );
-  } catch {
-    return false;
-  }
-}
-```
-
-**效果：**
-- `comate init` 检测到 plugin 版本后会显示"已安装"并跳过
-- 避免未来的重复安装
-
-### 2. 清理已有重复（cleanup 命令）
-
-**新增文件：** `bin/cleanup-duplicate-superpowers.mjs`
-
-**新增命令：** `comate cleanup`
-
-**工作流程：**
-1. 检查是否有 Claude Code plugin 版本
-2. 扫描 skills CLI 安装的 superpowers
-3. 安全删除重复的目录
-4. 保留 plugin 版本
-
-**安全机制：**
-- 只在检测到 plugin 版本时才执行清理
-- 只删除明确的 superpowers 目录
-- 不影响其他 skills
-
-## 测试覆盖
-
-### init.test.mjs
-- ✅ 检测空注册表
-- ✅ 检测有效的 plugin 安装
-- ✅ 检测其他 plugin 不误判
-- ✅ project scope 不检查 plugin（仅 global）
-
-### cli.test.mjs
-- ✅ cleanup 命令在帮助中列出
-- ✅ cleanup 命令可执行
-
-## 使用指南
-
-### 新用户（v0.9.24+）
-直接运行 `comate init`，系统会自动检测并跳过重复安装。
-
-### 已有重复安装的用户
-运行 `comate cleanup` 清理。
-
-### 验证状态
-```bash
-# 检查是否有重复
-ls ~/.agents/skills | grep -E "(using-super|brainstorm)"
-
-# 检查 plugin 版本
-cat ~/.claude/plugins/installed_plugins.json | grep superpowers
-```
-
-## 提交记录
-
-1. **7cee6e6** - fix: detect Claude Code plugin install to avoid duplicate superpowers
-   - 扩展检测逻辑
-   - 添加测试用例
-
-2. **82dd387** - feat: add cleanup command to remove duplicate superpowers install
-   - 新增清理命令
-   - 添加文档
-
-## 影响范围
-
-- **向后兼容：** 完全兼容，不影响现有功能
-- **新功能：** `comate cleanup` 命令
-- **行为变化：** `comate init` 会跳过 plugin 已安装的 superpowers
-- **磁盘空间：** 清理后可节省约 10-20MB
-
-## 相关文件
-
-- `bin/init.mjs` - 检测逻辑
-- `bin/init.test.mjs` - 检测测试
-- `bin/cleanup-duplicate-superpowers.mjs` - 清理脚本
-- `bin/cli.mjs` - CLI 入口
-- `bin/cli.test.mjs` - CLI 测试
-- `docs/CLEANUP_SUPERPOWERS.md` - 用户文档

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

@@ -1,103 +0,0 @@
-# 决策阻塞点清单（decision-points）
-
-规范路径：`comate/reference/decision-points.md`（单一真相源）
-
-本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
-
-## 先判定：这里真的需要用户输入吗？
-
-到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
-
-| 类别 | 判据 | 处理 |
-|------|------|------|
-| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
-| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
-| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
-
-三条落地准则：
-
-1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
-2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
-3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
-
-## 通用规则
-
-经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
-
-- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
-- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
-- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
-- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
-
-## 决策阻塞点清单
-
-以下是 comate 全流程中**核心决策点**的规范定义。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
-
-**本清单不穷举所有决策场景**——仅列出跨阶段、高频、影响流转的关键决策点。各 skill 内还有局部决策（如命名确认、dirty worktree 归因、PRD 选择等），由该 skill 自行定义并遵循本文首节的三类框架。
-
-## 核心决策点（跨阶段 / 流转关键）
-
-1. **开题产物审视确认**（open）
-   proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
-   - **对话来源**（`source_kind: conversation`）——范围此前未经任何用户拍板，三件套是第一次成形，属"用户决策"。暂停请用户确认或要求调整。
-   - **PRD 扇出且范围一致**——本 change 来自一份**已过门禁的 PRD**（可验证信号全部成立：`source_kind: file`、追踪的源是 PRD、`gate <prd> check` 返回 PASS、change 名已记入该 PRD `spawned_changes`），**且** proposal 的范围/目标/非目标忠实承接 gate 映射里本 change 认领的功能项、无擅自扩缩。此时范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，不产生新的 ≥2 有效选项 —— 只剩"继续"一个安全动作，属"自动处理"。**不 AskUserQuestion**，完整性检查通过即自动流转，并如实报告：承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
-   - **PRD 扇出但范围有偏差**——proposal 与 gate 映射不一致（擅自扩大/缩小范围、认领了未分配的功能项、漏掉已分配项）时，分歧重新出现，属"用户决策"。**必须 AskUserQuestion 暂停**，展示偏差点，请用户裁定按映射修正还是接受新范围。
-   引用：`comate-open` Step 5。
-
-2. **设计方案确认**（design / brainstorming）
-   brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
-   引用：`comate-design` Step 1c。
-
-3. **构建工作方式选择**（build）
-   开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
-   预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
-   引用：`comate-build` Step 3。
-
-4. **验证失败决策**（verify）
-   验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
-   - **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
-   - **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
-   - **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
-   引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
-
-5. **分支收尾方式选择**（verify / finishing-a-development-branch）
-   暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。前三项操作成功后写 `branch_status: handled`；丢弃工作写 `branch_status: discarded` 并停止流程，禁止执行 verify guard 或归档。
-   引用：`comate-verify` Step 3。
-
-6. **预设升级确认**（fix → full）
-   命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，先写 `phase_step: fix.upgrade-awaiting`，再暂停请用户确认。用户确认后执行原子转换 `state transition <name> fix-upgrade`，由脚本清除 fix 默认构建选项并进入 design。
-   引用：`comate-fix`「升级条件」。
-
-7. **构建期范围扩张**（build）
-   实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
-   引用：`comate-build` Step 4。
-
-## 其他决策场景（局部 / 特定 skill）
-
-以下决策点由特定 skill 自行定义，同样遵循本文首节的三类框架，但不属于跨阶段核心流转：
-
-### Gate 阶段（comate-gate）
-- **PRD 命名规范确认**：PRD 不符合命名规范时，AskUserQuestion 确认改名或拒绝
-- **PRD 未定稿处理**：PRD 标记 draft/WIP 时，确认是否继续评审
-- **阻断问题处理策略**：`blocking_open > 0` 时选择：先补 PRD / 授权带 TBD 继续 / 深度澄清 / 暂停
-- **拆分粒度与映射**（决策点 6 已列入核心）：功能项 → change 的映射由用户确认
-
-### Open 阶段（comate-open）
-- **继续已有 change / 新建**：顶层探测到活跃 change 时，确认继续还是新建
-- **Change 命名确认**：必须用用户指定或经 AskUserQuestion 确认的名称，不得自动生成
-
-### Build 阶段（comate-build）
-- **Dirty worktree 归因**：脏工作树按 `dirty-worktree.md` 协议分类后，不属于当前 change 或来源不确定时需要用户裁定：并入 / 拆分 / 保留 / 丢弃
-
-### Verify 阶段（comate-verify）
-- 已列入核心决策点 4、5
-
-## Red Flags — 出现这些念头就停下来检查
-
-| Agent 的念头 | 实际风险 |
-|--------------|----------|
-| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
-| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
-| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
-| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
-| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |

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

@@ -1,58 +0,0 @@
-# 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

@@ -1,89 +0,0 @@
-# 前置依赖检查清单（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。