@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate/tests/run.sh

@@ -1,101 +0,0 @@
-#!/bin/bash
-# run.sh — plain-bash runner for comate.bats when `bats` is not installed.
-#
-# It sources each @test body in a subshell with setup/teardown, providing the
-# minimal bats shims (`run`, `$status`, `$output`, `$BATS_TEST_DIRNAME`).
-# If real bats is available, prefer: bats skills/comate/tests/comate.bats
-#
-# Usage: bash skills/comate/tests/run.sh
-
-set -uo pipefail
-
-TEST_DIR="$(cd "$(dirname "$0")" && pwd)"
-BATS_FILE="$TEST_DIR/comate.bats"
-export BATS_TEST_DIRNAME="$TEST_DIR"
-
-# bats shim: run a command, capture combined output + status.
-run() {
-  local _out _rc
-  _out="$("$@" 2>&1)"
-  _rc=$?
-  output="$_out"
-  status="$_rc"
-  # shellcheck disable=SC2034
-  lines=()
-  local _l
-  while IFS= read -r _l; do lines+=("$_l"); done <<< "$_out"
-  return 0
-}
-
-# Extract test names and bodies from the .bats file.
-# A test is:  @test "name" {  ... }  with closing } at column 0.
-PASS=0
-FAIL=0
-FAILED_NAMES=()
-
-# shellcheck disable=SC1090
-source_helpers() {
-  # Pull setup(), teardown(), comate(), seed_open() definitions by sourcing
-  # a sanitized copy that strips the @test blocks.
-  local helpers
-  helpers="$(awk '
-    /^@test / { skip=1 }
-    skip==1 && /^}/ { skip=0; next }
-    skip==1 { next }
-    { print }
-  ' "$BATS_FILE")"
-  eval "$helpers"
-}
-
-run_one() {
-  local name="$1" body="$2"
-  ( # subshell isolates each test
-    set -uo pipefail
-    source_helpers
-    status=0; output=""
-    setup
-    _trap() { teardown 2>/dev/null || true; }
-    trap _trap EXIT
-    eval "$body"
-  )
-}
-
-main() {
-  local name="" body="" in_test=0
-  while IFS= read -r line; do
-    if [[ "$in_test" -eq 0 && "$line" =~ ^@test\ \"(.*)\"\ \{ ]]; then
-      name="${BASH_REMATCH[1]}"
-      body=""
-      in_test=1
-      continue
-    fi
-    if [[ "$in_test" -eq 1 && "$line" == "}" ]]; then
-      in_test=0
-      if run_one "$name" "$body" >/tmp/comate_test_out.$$ 2>&1; then
-        PASS=$((PASS+1))
-        printf '  ok   %s\n' "$name"
-      else
-        FAIL=$((FAIL+1))
-        FAILED_NAMES+=("$name")
-        printf '  FAIL %s\n' "$name"
-        sed 's/^/       /' /tmp/comate_test_out.$$
-      fi
-      continue
-    fi
-    if [[ "$in_test" -eq 1 ]]; then
-      body+="$line"$'\n'
-    fi
-  done < "$BATS_FILE"
-  rm -f /tmp/comate_test_out.$$
-
-  echo ""
-  echo "comate tests: $PASS passed, $FAIL failed"
-  if [ "$FAIL" -gt 0 ]; then
-    printf 'Failed:\n'
-    printf '  - %s\n' "${FAILED_NAMES[@]}"
-    exit 1
-  fi
-  exit 0
-}
-
-main

package/skills/comate-archive/SKILL.md

@@ -1,63 +0,0 @@
----
-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`。

package/skills/comate-build/SKILL.md

@@ -1,278 +0,0 @@
----
-name: comate-build
-description: "comate 阶段 3：计划与构建。用 /comate-build 调用。制定计划并选择执行方式（subagent 或直接执行）实施。"
----
-
-# comate 阶段 3：计划与构建（Build）
-
-## 前置条件
-
-- Design Doc 已创建（阶段 2 完成）
-- 活跃 change 存在
-
-## 步骤
-
-### 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 build
-```
-
-**幂等性检查**：
-
-1. 读取 `.comate.yaml` 的 `plan`、`isolation`、`build_mode`、`tdd_mode`、`phase_step`、`phase_step_data`
-
-2. **检查是否被依赖阻塞**（最高优先级检查）：
-   - 若 `phase_step` 为 `build.blocked-by-<dependency>`：
-     - 从 `phase_step` 或 `phase_step_data` 中提取依赖的 change 名称
-     - 运行 `bash "$COMATE" dependency <dependency> archived` 检查归档目录中是否存在该 change 且其 `.comate.yaml` 明确记录 `archived: true`；不得用“不在活跃列表”推断归档完成
-     - **若依赖已归档**：
-       ```bash
-       bash "$COMATE" state <name> set phase_step build.options-confirmed
-       bash "$COMATE" state <name> set phase_step_data null
-       ```
-       清除阻塞标记，说明「依赖 change <dependency> 已完成，继续当前 change 的 build」，继续第 3 步检查
-     - **若依赖未归档**：提示「当前 change 正在等待 <dependency> 完成。请先完成 <dependency> 的全流程后再继续。」，**立即退出**
-
-3. **已完成 Step 3（工作方式已选定）** 的判定条件：
-   - `isolation`、`build_mode`、`tdd_mode` **三个字段全部已设置且非 null**
-   - 或 `phase_step` 值为 `build.options-confirmed`
-
-4. **幂等分支**：
-   - **三个决策字段全部已设置** → 跳过 Step 3a-3c，说明「工作方式已选定：isolation={value}, build_mode={value}, tdd_mode={value}」，直接进入执行（加载对应技能）
-   - **任一字段未设置或为 null**：
-     - 若 `phase_step` 为 `build.plan-created` 或 `build.plan-recorded` → 继续对应步骤（见下方第 5 点）
-     - 若 `plan` 未设置 → 从 Step 1 开始
-     - 若 `plan` 已设置但决策未完成 → 从 Step 3 开始
-
-5. **断点恢复**（根据 `phase_step` 值）：
-   - `phase_step` 为 `build.plan-created`（或旧版 `1`）→ 从 Step 2 开始并改写新格式
-   - `phase_step` 为 `build.plan-recorded` / `build.options-awaiting`（或旧版 `2`）→ 从 Step 3 恢复并改写新格式
-   - `phase_step` 为 `build.options-confirmed`（或旧版 `3-confirmed`）→ 直接加载执行技能并改写新格式
-   - `phase_step` 为 `build.blocked-by-*` → 见第 2 点的依赖阻塞检查
-
-6. **已进入执行阶段**（plan 已设置、决策已完成）：
-   - 读 tasks.md 找第一个未勾选任务继续
-   - 已提交的任务不得重复提交
-   - 上下文压缩恢复时，重新加载对应的执行技能，然后继续未完成的任务
-
-### 1. 制定计划
-
-**立即执行：** 使用 Skill 工具加载 `superpowers:writing-plans`。禁止跳过。计划要求：
-- 保存至 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
-- 引用设计文档，拆分为可执行任务
-- **Plan 文件头必须含关联元数据**：
-
-```yaml
----
-change: <name>
-design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
-base-ref: <实施前的 git rev-parse HEAD>
----
-```
-
-`base-ref` 用于验证阶段跨提交统计改动规模。创建计划时先 `git rev-parse HEAD` 记录。
-
-**步骤完成后记录**：
-
-```bash
-bash "$COMATE" state <name> set phase_step build.plan-created
-```
-
-### 2. 记录计划路径
-
-```bash
-bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.md
-bash "$COMATE" state <name> set phase_step build.plan-recorded
-```
-
-无需手动改 phase，guard 会在退出条件满足后自动流转。
-
-### 3. 选择工作方式（决策阻塞点 3）
-
-就工作区隔离、执行方式、TDD 模式做**一个联合决策**。规则与判定协议见 `comate/reference/decision-points.md`（先判定"三类行动"，第 3 条）。
-
-#### 3a. 能力预检（展示选项前先做）
-
-逐维度检查当前平台/仓库实际可执行的选项，只保留可执行者：
-
-- **isolation**（脚本枚举仅 `branch` / `worktree`）
-  - `worktree`：仅当 `superpowers:using-git-worktrees` skill 可用时保留；不可用则剔除。
-  - `branch`：始终可用（HEAD detached 时先提示用户切到实分支）。
-- **build_mode**
-  - `subagent-driven-development`：仅当当前平台有真实后台子 agent / Task 派发能力时保留；无则剔除。
-  - `executing-plans`：始终可用。
-- **tdd_mode**：`tdd` / `direct` 始终可用。
-
-#### 3b. 唯一选项自动应用（属"自动处理"，不阻塞）
-
-预检后某维度只剩一个可执行选项，**直接写入并说明原因，不为它单独问用户**。例如：
-
-- 仅 `executing-plans` 可用（无后台派发能力）→ 自动写 `build_mode: executing-plans`，说明"无后台子 agent 能力"。
-- 仅 `branch` 可用（`using-git-worktrees` 未安装）→ 自动写 `isolation: branch`，说明"worktree skill 不可用"。
-
-多个维度都只剩单值时，一并自动写入并逐条说明；三个维度全部只剩单值时本决策点整体跳过，直接进入 Step 3c 执行。
-
-#### 3c. 联合决策（仍有 ≥2 有效选项的维度才问）
-
-对仍有多个有效选项的维度，**一次 AskUserQuestion 问清全部**，选 `branch` 时**分支名也在同一次确认**，不得先问是否继续再二次追问配置或命名。已在 3b 自动写入的维度不再列入问题。每个选项附推荐理由（推荐只说明倾向，不代替用户拍板）：
-
-- **工作区隔离**：`branch` 新建分支（简单快速，≤3 文件推荐）/ `worktree` 独立工作区（需并行或当前分支有未提交工作时推荐）。
-- **执行方式**：`subagent-driven-development`（任务 ≥3、独立、需双阶段审查）/ `executing-plans`（任务 ≤2 且无跨模块依赖，或来自 fix 预设）。
-- **TDD 模式**：`tdd`（涉及业务逻辑/新功能/API，推荐）/ `direct`（无需测试覆盖或用户明确跳过）。
-
-提问前先持久化：
-
-```bash
-bash "$COMATE" state <name> set phase_step build.options-awaiting
-```
-
-用户选择后（连同 3b 已自动应用的维度）写入：
-
-```bash
-bash "$COMATE" state <name> set isolation <branch|worktree>
-bash "$COMATE" state <name> set build_mode <subagent-driven-development|executing-plans|direct>
-bash "$COMATE" state <name> set tdd_mode <tdd|direct>
-bash "$COMATE" state <name> set phase_step build.options-confirmed
-```
-
-`isolation` 是脚本级硬约束，保持 `null` 时 `build → verify` 的 guard 和 `state transition build-complete` 都会失败。
-
-`build_mode: direct` 默认仅 fix 预设使用。full 流程只有用户明确要求跳过计划执行技能、且已记录显式 override 时才允许：
-
-```bash
-bash "$COMATE" state <name> set direct_override true
-bash "$COMATE" state <name> set build_mode direct
-```
-
-无 `direct_override: true` 时，full 流程的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
-
-**TDD 模式**：
-
-| 选项 | 含义 | 适用场景 |
-|------|------|---------|
-| `tdd` | 每个任务先写失败测试再实现 | 推荐。涉及业务逻辑、新功能、API 的改动 |
-| `direct` | 直接实现，不强制 TDD 流程 | 不需要测试覆盖的改动，或用户选择跳过测试直接写代码。fix 预设默认 `direct` |
-
-`tdd_mode` 是脚本级硬约束，full 流程在离开 build 阶段前必须选择 `tdd` 或 `direct`，否则 guard 和 `state transition build-complete` 都会失败。
-
-**执行隔离**：
-- **branch**：`git checkout -b <name>`，后续在新分支工作
-- **worktree**：必须使用 Skill 工具加载 `superpowers:using-git-worktrees` 创建隔离工作区，禁止用普通 shell 绕过；不可用时停止并提示安装。
-
-**加载执行技能**：使用 Skill 工具加载所选技能。不可用时停止并提示安装，不要用普通对话替代。加载后按其指引执行：按计划做任务、完成 tasks.md 勾选（`- [ ]` → `- [x]`）、每个任务完成后提交代码。
-
-**任务状态同步（硬约束）**：
-
-无论选择哪种 `build_mode`，**每完成一个任务后必须立即**：
-1. 在 `tasks.md` 中勾选对应任务：`- [ ]` → `- [x]`
-   - **如果任务有子任务**（缩进的 `- [ ]` 列表），必须**先勾选所有子任务，再勾选父任务**
-   - 禁止只勾选父任务而遗漏子任务
-   - 示例：
-     ```markdown
-     - [x] 定义 domain 模型
-       - [x] unit_rule.go：单元规则领域模型
-       - [x] keyword_rule.go：关键词规则领域模型
-       - [x] creative_rule.go：创意规则领域模型
-     ```
-2. 提交任务状态：
-   ```bash
-   git add tasks.md
-   git commit -m "chore: mark task N as completed"
-   ```
-3. 继续下一个任务
-
-- `build_mode: subagent-driven-development`：**主控 agent 在每个 subagent 完成并通过 review 后，立即更新 tasks.md（包括所有子任务）并提交**。禁止等所有任务完成后批量勾选。
-- `build_mode: executing-plans`：**当前 agent 在每个任务完成后立即更新 tasks.md（包括所有子任务）并提交**。
-- `build_mode: direct`：同 `executing-plans`。
-
-**TDD 执行约束（Step 3b）**：
-
-若 `tdd_mode: tdd`：
-- `build_mode: executing-plans`：加载执行技能后、执行第一个任务前，**立即**使用 Skill 工具加载 `superpowers:test-driven-development` 一次，禁止跳过。之后每个任务按已加载的 Red-Green-Refactor 循环执行，不得跳过失败测试验证阶段，后续任务不重复加载。上下文压缩恢复后重新加载一次，再从第一个未勾选任务继续。
-- `build_mode: subagent-driven-development`：派发每个子 agent 时，必须在 prompt 中显式注入 TDD 硬约束：**"You MUST follow TDD: for each task, write a failing test first, watch it fail, then write minimal code to pass. No production code without a failing test first."**。不得依赖其他配置隐式触发，必须明写在 dispatch prompt 中。
-- `build_mode: direct`：仅在 full 流程已设置 `direct_override: true` 时允许。执行第一个任务前，**立即**使用 Skill 工具加载 `superpowers:test-driven-development` 一次，由当前 agent 按 Red-Green-Refactor 循环执行每个任务；不得把 `direct` 理解为跳过失败测试验证。
-
-若 `tdd_mode: direct`：按正常流程执行，不强制 TDD。
-
-### 4. Spec 增量更新（决策阻塞点 7）
-
-实施中发现初版 spec 不完整时，按规模分级。规则见 `comate/reference/decision-points.md` 第 7 条。
-
-| 规模 | 触发 | 做法 |
-|------|------|------|
-| 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md |
-| 中 | 接口变更、新增组件、数据流变化 | **AskUserQuestion 确认后**加载 `superpowers:brainstorming` 更新 Design Doc + delta spec |
-| 大 | 全新 capability | **AskUserQuestion 确认拆分后**用 `/comate-open` 创建独立 change，**当前 change 的 build 流程立即终止** |
-
-**50% 阈值**：以 tasks.md 初始任务总数为基准，新增任务超过总数一半即视为超范围，**必须 AskUserQuestion 暂停**决定是否拆分。创建独立 change 必须调 `/comate-open`，不得直接调 `/opsx:new`。
-
-凡需 AskUserQuestion 决定范围扩张时，提问前先写 `phase_step: build.scope-awaiting`；用户决定继续当前 change 后恢复为 `build.options-confirmed`。
-
-**大规模扩张（全新 capability）确认拆分后的流程终止规则**：
-
-1. 用 `/comate-open` 创建独立 change `<new-change-name>`
-2. **当前 change `<current>` 的 build 流程立即暂停**，记录依赖关系：
-   ```bash
-   bash "$COMATE" state <current> set phase_step "build.blocked-by-<new-change-name>"
-   bash "$COMATE" state <current> set phase_step_data "<new-change-name>"
-   ```
-3. 提示用户：
-   ```
-   已创建独立 change <new-change-name>。
-   当前 change <current> 的 build 流程已暂停，等待 <new-change-name> 完成。
-   
-   请先完成 <new-change-name> 的全流程（design → build → verify → archive），
-   然后再继续 <current> 的 build。
-   ```
-4. **立即退出当前 /comate 调用**，不继续执行当前 change 的后续任务，不进入 Step 5
-
-**恢复被阻塞的 change**：
-
-当用户稍后运行 `/comate <current>` 时，Step 0 幂等性检查会发现 `phase_step` 包含 `blocked-by` 标记：
-- 检查依赖的 change 是否已归档
-- 若 `dependency <name> archived` 通过 → 清除阻塞标记，恢复 `phase_step` 为 `build.options-confirmed`，继续执行 tasks.md 中未完成的任务
-- 若未归档 → 提示用户先完成依赖 change，退出
-
-### 5. 上下文管理与 build 交接包
-
-Build 是最长阶段。为支持断点恢复：
-- **每完成一个 task**：立即勾选 tasks.md 并提交，确保状态持久化
-- **上下文压缩恢复**：先 `bash "$COMATE" state <name> recover build`，按 Recovery action 决定下一步
-- **用户手动修改恢复**：按 `comate/reference/dirty-worktree.md` 协议处理；归因后若 diff 暗示计划或 spec 变化，按 Step 4 分级
-
-全部任务完成、代码提交后，**生成 build → verify 交接包**（防止 plan/tasks 在两阶段间被偷改）：
-
-```bash
-bash "$COMATE" handoff <name> build --write
-```
-
-脚本写入 `impl_context` / `impl_hash`（plan + tasks 的 sha256）。verify 阶段 guard 会校验进入验证时的 plan/tasks 与此一致。
-
-## 退出条件
-
-- tasks.md 全部勾选，代码已提交
-- 已显式运行项目构建/测试命令并通过
-- `isolation` 已写为 `branch` 或 `worktree`
-- `build_mode` 已选（full 用 `direct` 需 `direct_override: true`）
-- `tdd_mode` 已写为 `tdd` 或 `direct`
-- `impl_context` / `impl_hash` 已写入
-- 源文件未漂移（`source_kind: file` 时，guard 复算知识库文件哈希与清单比对；`conversation` 跳过）
-- **阶段守卫**：`bash "$COMATE" guard <name> build --apply` 全 PASS 后自动流转到 `phase: verify`
-
-guard 优先读项目配置命令（change 的 `.comate.yaml` 或仓库根 `.comate.yaml`/`comate.yaml`）的 `build_command` / `verify_command`；未配置才回退 `npm run build`、Maven、Cargo 探测。构建失败时 guard 打印失败输出作为排查证据。
-
-```bash
-bash "$COMATE" guard <name> build --apply
-```
-
-## 自动流转
-
-> **REQUIRED NEXT SKILL：** 调用 `comate-verify` skill 进入验证与收尾。

package/skills/comate-design/SKILL.md

@@ -1,178 +0,0 @@
----
-name: comate-design
-description: "comate 阶段 2：深度设计。用 /comate-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
----
-
-# comate 阶段 2：深度设计（Design）
-
-## 前置条件
-
-- 活跃 change 已存在（proposal.md、design.md、tasks.md）
-- 无 Design Doc
-
-## 步骤
-
-### 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 design
-```
-
-**幂等性检查**：
-
-1. 读取 `.comate.yaml` 的 `design_doc`、`handoff_context`、`handoff_hash`、`phase_step`
-
-2. **已完成 Step 1c（方案已确认）** 的判定条件（按优先级，首个命中即算）：
-   
-   a. **phase_step 明确标记已确认**（最高优先级）：
-      - `phase_step` 值为 `design.approval-confirmed` 或 `design.complete`（旧版 `1c-confirmed` / `2` 兼容一次）
-      - → **立即判定为已完成 Step 1c**，跳过 Step 1a-1c
-   
-   b. **Design Doc 文件存在且格式正确**（次优先级）：
-      - `design_doc` 已设置且文件存在
-      - frontmatter 含 `comate_change: <name>`
-      - frontmatter 含 `role: technical-design`
-      - frontmatter 含 `canonical_spec: openspec`
-      - 文件内容非空（除了 frontmatter 外有实质设计内容）
-      - → **判定为已完成 Step 1c**，跳过 Step 1a-1c
-   
-   **说明**：之所以 `phase_step` 优先级更高，是因为它是原子操作记录的决策状态，即使 Design Doc 文件创建失败或被误删，也能防止重复进入决策流程。
-
-3. **幂等分支**：
-   - **已完成 Step 1c 且 Design Doc 存在** → 跳过 Step 1a-1c，检查交接包：
-     - 若 `handoff_context` 和 `handoff_hash` 已设置且验证通过 → 直接进入 Step 2 的 guard 检查
-     - 若交接包缺失或 hash 不匹配 → 重新生成交接包（`bash "$COMATE" handoff <name> design --write`），**但不重新 brainstorming，不重新确认方案**，然后进入 Step 2
-   - **已确认但 Design Doc 缺失** → 从 `.comate/design-candidate.md` 恢复已确认方案并创建 Design Doc；候选文件也缺失时停止并报告状态损坏，不得假称 Design Doc 已存在，也不得重新向用户询问同一决策
-   - **未完成 Step 1c** → 继续 Step 1a
-
-4. **断点恢复**（根据 `phase_step` 值）：
-   - `phase_step` 为 `design.handoff-written`（或旧版 `1a`）→ 从 Step 1b 开始并改写新格式
-   - `phase_step` 为 `design.brainstorm-complete` / `design.approval-awaiting`（或旧版 `1b`）→ 从候选文件恢复 Step 1c 并改写新格式
-   - `phase_step` 为 `design.approval-confirmed` 或 `design.complete` → 见第 3 点幂等分支
-
-5. **特别注意**：即使上下文压缩或会话中断，只要 `phase_step` 已标记 `design.approval-confirmed` 或 Design Doc 文件存在且格式正确，**就不得重新执行 brainstorming 或重新要求用户确认方案**。
-
-### 1a. 生成 OpenSpec → Superpowers 交接包
-
-**必须由脚本生成，不允许 agent 临场手写 summary 代替。**
-
-```bash
-bash "$COMATE" handoff <name> design --write
-# 记录步骤完成
-bash "$COMATE" state <name> set phase_step design.handoff-written
-```
-
-脚本生成 `openspec/changes/<name>/.comate/handoff/design-context.{json,md}` 并在 `.comate.yaml` 写入 `handoff_context` / `handoff_hash`。默认是 **compact 可追溯摘录**（含脚本标记 `Generated-by: comate`、source path、line range、sha256），不是 agent summary。需全文时加 `--full`。
-
-交接包来源：`proposal.md`、`design.md`、`tasks.md`、`specs/*/spec.md`。
-
-### 1b. 执行 Brainstorming（带上下文）
-
-**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming`，ARGUMENTS 包含：
-
-```
-Change: <name>
-OpenSpec Context Pack: openspec/changes/<name>/.comate/handoff/design-context.md
-Machine handoff: openspec/changes/<name>/.comate/handoff/design-context.json
-
-OpenSpec 产物是上游事实源，不要重新定义需求，不要重写 proposal/spec。
-基于交接包做深度技术设计：实现方案、技术风险、测试策略、边界条件。
-如发现 delta spec 缺少验收场景，只能提出 Spec Patch 回写 OpenSpec delta spec；不要在 Design Doc 中创建第二份需求 spec。
-
-Design Doc frontmatter 必须最小化，只含：
----
-comate_change: <name>
-role: technical-design
-canonical_spec: openspec
----
-```
-
-禁止跳过；该技能不可用时停止流程并提示安装 Superpowers，不要用普通对话替代。
-
-brainstorming 阶段不写最终 Design Doc；但必须把完整候选方案写入 `openspec/changes/<name>/.comate/design-candidate.md`，供确认与上下文恢复使用。
-
-**步骤完成后记录**：
-
-```bash
-bash "$COMATE" state <name> set phase_step design.brainstorm-complete
-```
-
-### 1c. 用户确认设计方案（决策阻塞点 2）
-
-**必须使用 AskUserQuestion 工具暂停等待用户明确确认设计方案**。规则见 `comate/reference/decision-points.md` 第 2 条。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
-
-展示摘要：采用的技术方案、关键取舍与风险、测试策略、Spec Patch（如有）。用户确认后才继续 Step 2；要求调整则继续迭代。
-
-提问前先确认候选文件非空，并持久化等待状态：
-
-```bash
-bash "$COMATE" state <name> set phase_step design.approval-awaiting
-```
-
-**确认后的处理顺序（不可颠倒）**：
-
-1. **立即记录决策状态**：
-   ```bash
-   bash "$COMATE" state <name> set phase_step design.approval-confirmed
-   ```
-
-2. **然后创建 Design Doc 文件**（保存到 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`），frontmatter 必须包含：
-   ```yaml
-   ---
-   comate_change: <name>
-   role: technical-design
-   canonical_spec: openspec
-   ---
-   ```
-
-3. **记录 design_doc 路径**：
-   ```bash
-   bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-   ```
-
-**说明**：候选方案先落盘，确认后再记录 `design.approval-confirmed` 并创建最终文件。这样中断恢复既不会重复提问，也不会丢失创建 Design Doc 所需内容。
-
-### 2. 更新 comate 状态
-
-```bash
-# 记录 design_doc 路径
-bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-
-# 如有 delta spec 变更，重新生成 handoff 以更新 hash
-bash "$COMATE" handoff <name> design --write
-
-# 记录步骤完成
-bash "$COMATE" state <name> set phase_step design.complete
-
-# 自动流转
-bash "$COMATE" guard <name> design --apply
-```
-
-无 delta spec 变更则跳过 handoff 重新生成。
-
-## 退出条件
-
-- Design Doc 已创建，frontmatter 含 `comate_change`、`role: technical-design`、`canonical_spec: openspec`
-- `handoff_context` / `handoff_hash` 已写入且 hash 与当前产物一致（guard 强制）
-- `design-context.md` 由脚本生成且含可追溯标记（guard 强制）
-- `design_doc` 已写入 `.comate.yaml`
-- **阶段守卫**：`bash "$COMATE" guard <name> design --apply` 全 PASS 后自动流转到 `phase: build`
-
-## 上下文压缩恢复
-
-```bash
-bash "$COMATE" state <name> recover design
-```
-
-脚本输出结构化恢复上下文，按 Recovery action 判断下一步。
-
-## 自动流转
-
-> **REQUIRED NEXT SKILL：** 调用 `comate-build` skill 进入计划与构建。