@house365/comate 0.10.3 → 1.0.2-next.0

package/docs/superpowers/plans/2026-09-13-fast-workflow.md

@@ -1,62 +0,0 @@
-# Fast Workflow Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task with review checkpoints.
-
-**Goal:** Add a constrained `fast` workflow that runs open → agent implementation/test evidence → archive while preserving state, scope, and verification guards.
-
-**Architecture:** Extend the existing flat `.comate.yaml` state machine with `workflow: fast` and a `fast-execute` phase. Reuse the existing proposal/tasks artifacts and archive command, add a machine-owned fast handoff plus verification report requirements, and keep full/fix behavior unchanged.
-
-**Tech Stack:** Bash, flat YAML state files, Bats tests, Markdown skills.
-
-**Spec:** This plan implements the fast workflow design agreed in conversation: skip standalone design/build/verify phases, but require bounded scope, implementation evidence, tests, and a guarded archive.
-
-## Global Constraints
-
-- Fast workflow must not add capability, change public interfaces, change database schema, add dependencies, or cross module boundaries.
-- Fast workflow must be recoverable from `.comate.yaml` and must not rely on conversation context.
-- Archive is allowed only after a successful fast verification report and handled branch status.
-- Existing `full` and `fix` workflows must retain their current behavior.
-
-### Task 1: Add fast state-machine support
-
-**Files:**
-- Modify: `skills/comate/scripts/comate-lib.sh`
-- Modify: `skills/comate/scripts/comate.sh`
-- Test: `skills/comate/tests/comate.bats`
-
-- [ ] **Step 1: Write failing state tests** for `workflow: fast`, `fast-execute` phase, and `fast-complete` transition.
-- [ ] **Step 2: Run the focused tests and confirm they fail** because the enum/transition is unsupported.
-- [ ] **Step 3: Implement the minimal enum, state fields, transition, and phase checks.** Fast initialization starts in `phase: open`; open completion routes to `phase: fast-execute`; fast completion routes to `phase: archive`.
-- [ ] **Step 4: Run focused tests and the full Bats suite.**
-
-### Task 2: Add fast execution handoff and guard
-
-**Files:**
-- Modify: `skills/comate/scripts/comate.sh`
-- Test: `skills/comate/tests/comate.bats`
-
-- [ ] **Step 1: Write failing tests** requiring a fast context package, verification report, test result, and bounded changed-file count before `fast-complete`.
-- [ ] **Step 2: Run focused tests and confirm the guard rejects missing evidence.**
-- [ ] **Step 3: Implement `handoff <name> fast --write` and `guard <name> fast --apply`.** The context hashes proposal/tasks and records changed files; the guard validates the report, test command/result, scope marker, and branch handling.
-- [ ] **Step 4: Run focused tests and the full Bats suite.**
-
-### Task 3: Add the fast skill and orchestrator routing
-
-**Files:**
-- Create: `skills/comate-fast/SKILL.md`
-- Modify: `skills/comate/SKILL.md`
-- Modify: `README.md`
-
-- [ ] **Step 1: Write the skill contract** for fast open, bounded implementation, evidence, upgrade conditions, and archive.
-- [ ] **Step 2: Add orchestrator detection** so explicit small bug/fix requests can select fast only when the user asks for the fast path; ordinary fixes continue using `comate-fix`.
-- [ ] **Step 3: Document commands, limits, recovery, and upgrade behavior.**
-- [ ] **Step 4: Run documentation consistency checks and the full Bats suite.**
-
-### Task 4: Verify branch and workflow behavior
-
-**Files:**
-- Test: `skills/comate/tests/comate.bats`
-
-- [ ] **Step 1: Add an end-to-end Bats scenario** covering fast init → open guard → implementation evidence → fast guard → archive preconditions.
-- [ ] **Step 2: Run the complete test suite.**
-- [ ] **Step 3: Review the diff for unchanged full/fix semantics and commit the feature.**

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。