@house365/comate 0.9.23 → 0.9.24

package/docs/multica-integration.md

@@ -0,0 +1,400 @@
+# comate 在 multica 中的集成方案
+
+## 问题诊断
+
+### 核心不兼容性
+
+- **comate**: Claude Code Agent Skills,依赖同步阻塞的 `AskUserQuestion` 工具在 7 个决策点暂停等待用户输入
+- **multica**: 无 TTY 的异步 agent runtime,以 issue 为任务单位,通过 `resume_session` 续接会话,人机交互走 issue comment
+
+**表现**: multica daemon 日志显示 `codex did not close stdout after stdin EOF; forcing shutdown`,因为 comate 调用的 `AskUserQuestion` 在无交互终端环境下挂起等待 stdin,最终被强制杀死。
+
+### 为什么不改 comate 本身
+
+comate 的交互本质是**持久化状态机**,而非 `AskUserQuestion` 工具本身:
+
+1. 每个决策点会将 `.comate.yaml` 写入 `*-awaiting` 标记(如 `design.approval-awaiting`)
+2. 每次 `/comate` 调用开头的 Step 0 **专门**检查这些 awaiting 标记并路由到对应子 skill 恢复执行
+3. 子 skill 的幂等性检查读取 `phase_step`,跳过已完成步骤,从断点继续
+
+`AskUserQuestion` 只是在交互式 CLI 场景下实现「落盘 awaiting → 等答复 → 恢复」循环的工具。在 multica 里,我们把同一个循环改成**异步三拍**:
+
+```
+决策点到达 → ① 确保 .comate.yaml 落 *-awaiting
+            ② 把问题+选项写成 issue comment
+            ③ 结束本次 task
+    ↓
+(人在 issue 评论区回答)
+    ↓
+issue rerun / 新消息触发 → comate Step 0 读到 *-awaiting → 断点恢复继续
+```
+
+这套转换**零改 comate 源码**,完全复用 comate 自带的 awaiting + 恢复机制。
+
+---
+
+## 适配方案
+
+### 架构选择
+
+| 维度 | 方案 | 理由 |
+|------|------|------|
+| 协议承载层 | agent `--instructions` | 最轻量,优先级高于 skill 措辞,单个 agent 立即生效 |
+| 交互载体 | issue comment | 与 multica 的 issue 工作单元天然对齐,有完整审计 |
+| skill 交付 | 本地安装优先,不导 workspace | claude runtime = 本地 Claude Code,自动加载 `~/.claude/skills`;仅跨 runtime 才需导入 |
+| 落地路径 | 先验证最小链路再推广 | 一个 change 跑到第一个决策点验证异步恢复可行 |
+
+### 核心协议:决策点重定向
+
+在 multica agent 的 `--instructions` 中注入以下指令(优先级高于 comate skill 的 `AskUserQuestion` 要求):
+
+```markdown
+## multica 环境下的决策点处理协议
+
+你在 multica 无 TTY 的异步 agent runtime 中运行。当 comate workflow 到达需要用户决策的点时:
+
+**禁止** 调用 `AskUserQuestion` 工具(该工具在 multica 后端不可用或会导致任务挂起)。
+
+**改为执行以下三步**:
+
+1. **落盘 awaiting 标记**:确保当前决策点对应的 `phase_step` 已写入 `.comate.yaml`
+   - 例如:`design.approval-awaiting`、`build.options-awaiting`、`verify.failure-awaiting`
+   - comate 脚本 `bash "$COMATE" state transition` 已自动处理,无需额外操作
+
+2. **发送 issue comment**:用 Bash 调用 multica CLI 在当前 issue 发评论。
+   **实测命令语法**(issue id 是位置参数,内容用 `--content`,评论触发的 agent 回复必须带 `--parent`):
+   ```bash
+   ~/.multica/bin/multica issue comment add "$MULTICA_ISSUE_ID" \
+     --parent "$TRIGGER_COMMENT_ID" \
+     --content-stdin << 'EOF'
+   【comate 决策点】
+
+   当前阶段: <phase>
+   等待标记: <phase_step>
+
+   问题: <清晰描述用户需要决定的事情>
+
+   选项:
+   1. <选项 A 及其说明>
+   2. <选项 B 及其说明>
+
+   请在评论中回复选项编号或关键词,然后 rerun 本 issue 继续。
+   EOF
+   ```
+   - `$MULTICA_ISSUE_ID` 从环境变量获取(未注入时用 `multica chat history --output json` 兜底)
+   - `$TRIGGER_COMMENT_ID` 是触发本次 task 的评论 id;省略 `--parent` 发顶层评论会被拒绝
+   - 多行内容用 `--content-stdin`,避免 Windows 下非 ASCII 被 mangle
+   - 选项描述要清晰,包含决策依据与影响
+
+3. **结束当前任务**:报告「已记录决策点并等待用户答复」,然后正常退出(exit 0)
+   - **不要**尝试继续执行后续步骤
+   - **不要**用默认值、推荐规则或历史偏好替代用户决策
+   - comate 的 Step 0 会在下次恢复时检测 awaiting 标记并路由
+
+**恢复逻辑**:用户在 issue 评论回答后执行 `multica issue rerun`,comate 的 `/comate` 入口 Step 0 会:
+- 读取 `.comate.yaml` 的 `phase_step` 发现 `*-awaiting` 标记
+- 直接路由到对应子 skill(如 `/comate-design`)
+- 子 skill 的幂等性检查跳过已完成步骤,从用户答复后的逻辑继续
+
+---
+
+## comate 决策点映射表
+
+| 决策点 | phase_step 标记 | 触发条件 | 需要决策的内容 |
+|--------|----------------|----------|----------------|
+| 1. 开题产物审视确认 | `open.review-awaiting` | proposal/design/tasks 完成且来源是对话(`source_kind: conversation`) | 确认三件套或要求调整 |
+| 2. 设计方案确认 | `design.approval-awaiting` | brainstorming 完成 | 确认采用的方案、关键取舍、测试策略、Spec Patch |
+| 3. 构建工作方式选择 | `build.options-awaiting` / `build.scope-awaiting` | 进入 build 阶段但 `build_mode`/`isolation`/`tdd_mode` 未设 | 工作区隔离(branch/worktree)、执行方式、TDD 模式 |
+| 4. 验证失败决策 | `verify.failure-awaiting` | 验证失败且属 WARNING/SUGGESTION 或 Spec 漂移 | 全部修复 / 逐项处理 / 接受偏差 |
+| 5. 分支收尾方式选择 | `verify.branch-awaiting` | 验证通过但 `branch_status` 仍为 `pending` | 本地合并 / 推送建 PR / 保持分支 / 丢弃工作 |
+| 6. 预设升级确认 | `fix.upgrade-awaiting` | fix 模式命中升级条件 | 确认从 fix 升级到 full workflow |
+| 7. 构建期范围扩张 | `build.scope-awaiting` | 新增任务超过初始任务总数 50% | 拆分新 change / 更新设计 / 继续构建 |
+
+**关键注意**:
+- CRITICAL 失败(构建失败/测试失败/安全问题)属「自动处理」,不发评论直接回退 build
+- PRD 扇出且范围一致属「自动处理」,不发评论直接流转
+- 预检后只剩一个可执行选项属「自动处理」,不发评论
+
+完整定义见 `comate/reference/decision-points.md`。
+```
+
+### multica 环境变量
+
+multica runtime 自动注入的环境变量(在 agent task 执行时可用):
+
+| 变量 | 说明 | 用途 |
+|------|------|------|
+| `MULTICA_ISSUE_ID` | 当前 issue 的 ID | 调用 `multica issue comment add` 时传入 |
+| `MULTICA_WORKSPACE_ID` | 当前 workspace 的 ID | 某些 CLI 命令需要 |
+| `MULTICA_TASK_ID` | 当前任务的 ID | 日志与审计 |
+
+---
+
+## 实施步骤
+
+### 1. 让 agent 能加载到 comate skill
+
+**先判断走哪条路——多数情况不用导入 workspace。**
+
+multica 的 claude runtime 底层就是本地 Claude Code CLI(日志实锤 `claude version 2.1.220 (Claude Code)`)。Claude Code 启动时本来就从 `~/.claude/skills` 加载 skill。所以:
+
+| 场景 | 做法 |
+|------|------|
+| **本机 runtime 已装 comate**(`~/.claude/skills/comate*` 存在,通常是 `comate init` 或仓库 symlink)| **无需导入**。agent task 由本地 Claude Code 执行,直接加载本地 comate,跑的是活代码 |
+| **跨 runtime**(云端 / 别人机器 / 未装 comate)| 才需要把 skill 导入 workspace,让 multica 分发下去 |
+
+确认本机是否已装:
+
+```bash
+ls ~/.claude/skills/ | grep comate     # 有则说明本地 runtime 已可用,跳过导入
+```
+
+**仅当需要跨 runtime 时**才导入(comate 是 10 个独立 skill,必须逐个导——主 skill 靠 `/comate-open` 等 slash command 分派,合并成一个会让分派断掉):
+
+```bash
+# 一个 archive 导一个 skill。--file 接受 .skill/.zip;archive 根下直接放 SKILL.md + reference/ + scripts/。
+# 关键:zip 内路径必须用正斜杠(Windows 的 Compress-Archive 产生反斜杠,会让 SKILL.md 里
+#       comate/reference/... 的引用失效),用 Python zipfile 打包最稳。
+for z in /path/to/comate-skills-pack/*.zip; do
+  multica skill import --file "$z" --on-conflict overwrite
+done
+
+# 确认附属 scripts/comate.sh 保留(子 skill 全靠它运行):
+multica skill files list <comate-skill-id>
+```
+
+> 注意:若本机既有本地 symlink 安装、又导入了 workspace skill,同名可能冲突。二选一,别同时用。
+
+### 2. 创建带适配指令的 multica agent
+
+```bash
+# 准备 instructions 文件
+cat > /tmp/comate-agent-instructions.md << 'EOF'
+你是一个运行 comate SDD workflow 的 agent。
+
+comate 是规约驱动开发(Spec-Driven Development)的编排器,包含五阶段: open → design → build → verify → archive,以及两个预设路径 fix/gate。
+
+## multica 环境下的决策点处理协议
+
+你在 multica 无 TTY 的异步 agent runtime 中运行。当 comate workflow 到达需要用户决策的点时:
+
+**禁止** 调用 `AskUserQuestion` 工具(该工具在 multica 后端不可用或会导致任务挂起)。
+
+**改为执行以下三步**:
+
+1. **落盘 awaiting 标记**: 确保当前决策点对应的 `phase_step` 已写入 `.comate.yaml`
+   - comate 脚本 `bash "$COMATE" state transition` 已自动处理
+
+2. **发送 issue comment**: 用 Bash 调用 multica CLI 在当前 issue 发评论
+   ```bash
+   ~/.multica/bin/multica issue comment add "$MULTICA_ISSUE_ID" \
+     --parent "$TRIGGER_COMMENT_ID" \
+     --content-stdin << 'EOF'
+   【comate 决策点】
+
+   当前阶段: <phase>
+   等待标记: <phase_step>
+
+   问题: <清晰描述用户需要决定的事情>
+
+   选项:
+   1. <选项 A 及其说明>
+   2. <选项 B 及其说明>
+
+   请在评论中回复选项编号或关键词,然后 rerun 本 issue 继续。
+   EOF
+   ```
+
+3. **结束当前任务**: 报告「已记录决策点并等待用户答复」,然后正常退出
+   - **不要**尝试继续执行后续步骤
+   - **不要**用默认值或推荐规则替代用户决策
+
+**恢复逻辑**: 用户答复后执行 `multica issue rerun`,comate 的 Step 0 会检测 `*-awaiting` 标记并恢复。
+
+**关键 awaiting 标记**:
+- `open.review-awaiting`: 开题产物审视
+- `design.approval-awaiting`: 设计方案确认
+- `build.options-awaiting` / `build.scope-awaiting`: 构建选项 / 范围扩张
+- `verify.failure-awaiting` / `verify.branch-awaiting`: 验证失败 / 分支收尾
+- `fix.upgrade-awaiting`: 预设升级
+
+完整映射见 workspace 文档 `docs/multica-integration.md`。
+
+---
+
+其余遵循 comate skill 的完整指令。
+EOF
+
+# 创建 agent
+multica agent create \
+  --name "comate-sdd" \
+  --description "comate 规约驱动开发编排器(适配 multica 异步决策)" \
+  --instructions "$(cat /tmp/comate-agent-instructions.md)" \
+  --runtime-id <你的-runtime-id> \
+  --model claude-opus-4-8 \
+  --thinking-level high \
+  --max-concurrent-tasks 2 \
+  --visibility workspace
+```
+
+**获取 runtime-id**:
+
+```bash
+multica runtime list --output json | jq -r '.[0].id'
+```
+
+### 3. 分配 comate skills 给 agent(仅跨 runtime 模式需要)
+
+**本地已装 comate 时跳过本节**——本地 Claude Code 自动加载 `~/.claude/skills`,agent 无需 workspace 分配即可用 `/comate`。
+
+仅当第 1 节走了「跨 runtime 导入」时才需要把 workspace skill 分配给 agent:
+
+```bash
+# 获取 agent id(实测:list 用 --output table 取 ID 列;下面 jq 示例需环境有 jq)
+AGENT_ID=<comate-sdd 的 id>
+
+# 收集 workspace 里的 comate skill id,逗号分隔
+IDS="<id1>,<id2>,..."
+
+# add 不替换现有分配(实测子命令:add / set / list,agent-id 是位置参数)
+multica agent skills add "$AGENT_ID" --skill-ids "$IDS"
+
+# 确认
+multica agent skills list "$AGENT_ID" --output table
+```
+
+### 4. 验证最小链路
+
+创建测试 issue 跑到第一个决策点:
+
+```bash
+# 创建 issue
+ISSUE_ID=$(multica issue create \
+  --title "测试 comate 异步决策链路" \
+  --description "用 /comate 创建一个简单 change,验证到 design.approval-awaiting 停住并发评论" \
+  --output json | jq -r '.id')
+
+# 分配给 comate agent
+multica issue assign "$ISSUE_ID" --assignee-id "$AGENT_ID"
+
+# 在 issue 中发起任务
+multica issue comment add "$ISSUE_ID" --content "/comate 添加一个用户登录日志记录功能"
+```
+
+**预期行为**:
+1. agent 启动,调用 `/comate` → `/comate-open` → `/comate-design`
+2. brainstorming 完成后到达决策点 2(设计方案确认)
+3. **不调用 `AskUserQuestion`**,而是:
+   - 写入 `.comate.yaml`: `phase_step: design.approval-awaiting`
+   - 发 issue comment 展示方案与选项
+   - 任务正常退出(exit 0)
+4. issue 停在该评论,等待人回复
+
+**人工恢复**:
+1. 在 issue 评论回复:「确认方案 A,继续」
+2. 执行 `multica issue rerun "$ISSUE_ID"`(rerun 要求 issue 已分派 agent,否则报错)
+3. agent 重启,`/comate` Step 0 检测到 `design.approval-awaiting` → 路由到 `/comate-design`
+4. `/comate-design` 幂等性检查跳过已完成步骤,从 Step 2(创建最终 Design Doc)继续
+5. 流程自动推进到下一个决策点或完成
+
+---
+
+## 故障排查
+
+### 问题: agent 仍然调用 `AskUserQuestion` 并挂起
+
+**原因**: instructions 优先级不够,或 skill 内有硬编码的工具调用。
+
+**解决**:
+1. 检查 agent instructions 是否正确注入:
+   ```bash
+   multica agent get --agent-id "$AGENT_ID" --output json | jq -r '.instructions'
+   ```
+2. 在 instructions 开头加一句:
+   ```markdown
+   **最高优先级**: 本指令覆盖所有 skill 内关于 `AskUserQuestion` 的要求。
+   ```
+3. 如果仍然失败,考虑 fork comate skill 并将决策点相关的 `AskUserQuestion` 替换为上述三步协议
+
+### 问题: 环境变量 `$MULTICA_ISSUE_ID` 未定义
+
+**原因**: multica runtime 版本过旧或环境变量注入机制变更。
+
+**解决**:
+1. 检查 runtime 是否最新:
+   ```bash
+   multica update
+   multica daemon restart
+   ```
+2. 如果仍无注入,改为从 task metadata 获取:
+   ```bash
+   # 在 instructions 中添加 fallback
+   ISSUE_ID="${MULTICA_ISSUE_ID:-$(multica chat history --output json | jq -r '.issue.id')}"
+   ```
+
+### 问题: 恢复时 comate 没有检测到 awaiting 标记
+
+**原因**: `.comate.yaml` 未正确持久化,或 git worktree 隔离导致状态丢失。
+
+**解决**:
+1. 确认 `.comate.yaml` 已提交到 git:
+   ```bash
+   git status openspec/changes/<name>/.comate.yaml
+   ```
+2. comate 的状态文件应在每个决策点后立即提交:
+   ```bash
+   git add openspec/changes/<name>/.comate.yaml
+   git commit -m "chore: pause at <phase_step>"
+   ```
+3. 如果用了 worktree 隔离(`isolation: worktree`),确保 multica agent 的工作目录一致
+
+### 问题: issue comment 发送失败
+
+**原因**: multica CLI 路径错误,或权限不足。
+
+**解决**:
+1. 确认 CLI 可用:
+   ```bash
+   which ~/.multica/bin/multica
+   ~/.multica/bin/multica --version
+   ```
+2. 测试评论权限:
+   ```bash
+   ~/.multica/bin/multica issue comment add "$ISSUE_ID" --content "测试"
+   ```
+3. 如果权限不足,检查 agent 的 `--custom-env` 是否包含认证 token
+
+---
+
+## 已知限制
+
+1. **Claude Code 特有工具**: `AskUserQuestion` 是 Claude Code 的工具,multica 的 codex provider 根本没有该工具,所以必须通过 instructions 重定向。claude provider 有该工具但在无 TTY 环境下会挂起。
+
+2. **决策点的粒度**: comate 的 7 个核心决策点已覆盖,但局部决策(如 dirty worktree 归因、PRD 选择)仍在各 skill 内定义,需要逐一适配。
+
+3. **用户答复格式**: 目前依赖人在评论中用自然语言答复,agent 恢复时需要解析评论。可优化为结构化格式(JSON / YAML)或引入 multica 的 property 字段。
+
+4. **并发**: 同一个 change 如果有多个 agent 并发操作,`.comate.yaml` 可能冲突。建议 `--max-concurrent-tasks 1` 或用 multica 的 issue locking。
+
+---
+
+## 后续优化方向
+
+1. **独立 adapter skill**: 将协议封装为 `comate-multica-adapter` skill,instructions 只需一句「优先遵守 adapter skill」,更易维护与版本化。
+
+2. **结构化答复**: 在 issue comment 中用 JSON/YAML 承载用户选择,agent 恢复时直接解析,减少自然语言理解的不确定性。
+
+3. **autopilot 触发**: 当 issue 移动到「待决策」状态列时,自动触发人工审核提醒,而非依赖 rerun。
+
+4. **决策历史审计**: 将每个决策点的问题、选项、用户答复记录到 `.comate/decisions.jsonl`,形成可追溯的决策链。
+
+5. **批量恢复**: 支持一次 rerun 解决多个相邻的小决策,而非每个决策点都要一次往返。
+
+---
+
+## 参考
+
+- comate 决策阻塞点定义: `comate/reference/decision-points.md`
+- comate 状态机契约: `comate/scripts/comate-lib.sh` (`FIELD_ORDER` + `state transition`)
+- multica CLI 文档: `multica --help` / `multica <command> --help`
+- multica agent runtime 环境变量: 待官方文档补充,当前从实测推断

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.23",
+  "version": "0.9.24",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

package/skills/comate/scripts/comate.sh

@@ -2005,16 +2005,18 @@ doctor() {
   fi
 
   # Superpowers skill directory — check known skill roots only (bounded; an
-  # unbounded $HOME scan is too slow on large home directories).
-  # Plugin roots matter too: Claude Code installs superpowers as a plugin under
-  # plugins/{cache,data}/, not under skills/. maxdepth 3 keeps deeper
-  # marketplace docs dirs (e.g. marketplaces/*/docs/superpowers) from matching.
+  # unbounded $HOME scan is too slow on large home directories). The skills CLI
+  # (including `claude codeskills add`) installs Superpowers as a flat bundle of
+  # named skills (for example using-superpowers/SKILL.md), so looking only for
+  # a directory named "superpowers" produces a false warning.
   local sp_found=0 root
   for root in \
-    "./.claude/skills" "./.cursor/skills" "./.codex/skills" \
-    "$HOME/.claude/skills" "$HOME/.config/skills" "$HOME/.cursor/skills" "$HOME/.codex/skills" "$HOME/.gemini/skills" \
+    "./.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" \
     "./.claude/plugins" "$HOME/.claude/plugins"; do
-    if [ -d "$root" ] && find "$root" -maxdepth 3 -type d -name 'superpowers*' -print -quit 2>/dev/null | grep -q .; then
+    if [ -f "$root/using-superpowers/SKILL.md" ] || \
+       [ -f "$root/brainstorming/SKILL.md" ] || \
+       { [ -d "$root" ] && find "$root" -maxdepth 3 -type d -name 'superpowers*' -print -quit 2>/dev/null | grep -q .; }; then
       sp_found=1; break
     fi
   done

package/skills/comate/tests/comate.bats

@@ -539,6 +539,16 @@ SH
   [ "$status" -eq 0 ]
 }
 
+@test "doctor recognizes Claude Code skills-cli Superpowers layout" {
+  local fake_home="$WORK/fake-home"
+  mkdir -p "$fake_home/.claude/skills/using-superpowers"
+  printf '# using-superpowers\n' > "$fake_home/.claude/skills/using-superpowers/SKILL.md"
+  run env HOME="$fake_home" bash "$COMATE" doctor
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Superpowers skills found"* ]]
+  [[ "$output" != *"Superpowers skills not found"* ]]
+}
+
 @test "dependency archived requires an archived=true record" {
   comate state dep init full
   run comate dependency dep archived