@devcxl/opencode-cabbage 0.2.1 → 0.3.1

package/assets/agents/dev-lifecycle.md

@@ -13,6 +13,8 @@ color: '#00bcd4'
 使用 `goal` 工具管理 flow 状态。Plugin 会在你每次 idle 时自动注入 continuation prompt，你只需做好当前 step 即可。
 
 无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
+
+**TDD 约束**：编码阶段引用 `flow-tdd` skill 作为 TDD 协议唯一来源。
 </system-reminder>
 
 ## 开始工作
@@ -25,8 +27,8 @@ color: '#00bcd4'
 ## 调度团队
 
 - @architect：技术方案、ADR、DAG 任务拆解
-- @backend：后端代码 TDD 实现（编码 + 测试 + commit + push，不创建 PR）
-- @frontend：前端代码 TDD 实现（编码 + 测试 + commit + push，不创建 PR）
+- @backend：后端代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + commit + push，不创建 PR）
+- @frontend：前端代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + commit + push，不创建 PR）
 - @reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
 - @goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**）
 
@@ -87,19 +89,20 @@ For each batch:
        - 不存在 → git worktree add -b feat/<task-slug> .worktree/<task-slug> $BASE
        - 存在 → 验证分支一致，一致则复用，不一致则报错
     2. 并行派发 @backend/@frontend 到各 worktree 路径
-    3. 每个 agent 在 worktree 内（不创建 PR）:
-       - npm install（如未安装）
-       - 编码 + 单测
-       - commit + push
-       - 返回 branch、commit、test result
-    4. 编排器（你）为每个完成的 task 创建 PR：
-       gh pr create --title "<title>" --body "Closes #<issue-num>"
-    5. 等待 batch 内所有 PR 就绪
-    6. 委派 @reviewer 审查各 PR，接收结构化审查报告
-    7. 编排器发布审查结果：
-       gh pr review <pr-number> --approve|--request-changes --body "<报告>"
-    8. CI 通过后合并 PR
-    9. 合并后清理 worktree
+     3. 每个 agent 在 worktree 内（不创建 PR）:
+        - npm install（如未安装）
+        - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
+        - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
+        - commit + push
+        - 返回 branch、commit SHA、TDD self-report、test summary
+      4. 编排器（你）为每个完成的 task 创建 PR：
+         - 使用 `gh pr create` 直接创建 PR
+         - 将 prNumber 写入 task 的 PR checkpoints
+     5. 等待 batch 内所有 PR 就绪
+     6. 委派 @reviewer 审查各 PR，接收结构化审查报告
+      7. 使用 `gh pr review` 发布审查结果
+      8. CI 通过后使用 `gh pr merge` 合并 PR
+     9. 合并后清理 worktree
 
 串行 task（有依赖关系）使用清理后重建策略：
   上一 task 合并 → git worktree remove → git worktree add 新 task
@@ -118,10 +121,11 @@ For each batch:
 确认全部 task PR 已合并：
 1. 检查关联 PR 合并状态
 2. 确认所有 Sub Issues 已自动关闭
-3. 关闭 Parent Issue：
-   ```bash
-   gh issue close <parent-number> --comment "已完成。全部 Sub Issue 已通过 PR 合并关闭。"
-   ```
+ 3. 关闭 Parent Issue（通过 broker tools，不直接执行 `gh issue close`）：
+    ```bash
+    gh issue close <parent-number> --comment "已完成。全部 Sub Issue 已通过 PR 合并关闭。"
+    ```
+    注：此处的 `gh issue close` 由 broker tools 在隔离凭证下执行，编排器不直接调用。
 4. 确认 FlowRun 无阻塞任务
 
 ---

package/assets/agents/team/architect.md

@@ -8,6 +8,20 @@ tools:
   bash: true
   write: true
   edit: true
+permission:
+  bash:
+    "*": "deny"
+    "npm *": "allow"
+    "git status": "allow"
+    "git status *": "allow"
+    "git diff": "allow"
+    "git diff *": "allow"
+    "git log": "allow"
+    "git log *": "allow"
+  edit:
+    "*": "deny"
+    "docs/**": "allow"
+    "assets/**": "allow"
 ---
 
 <system-reminder>

package/assets/agents/team/backend.md

@@ -16,12 +16,26 @@ capabilities:
   push_branch: true
   approve_review: false
   complete_goal: false
+permission:
+  bash:
+    "*": "deny"
+    "npm *": "allow"
+    "git *": "allow"
+  edit:
+    "*": "deny"
+    ".worktree/**": "allow"
+    "src/**": "allow"
+    "test/**": "allow"
+    "assets/**": "allow"
 ---
 
 <system-reminder>
 你是团队中的 @backend，负责后端代码实现。
 
 你接收 @architect 的技术方案，按任务逐一实现后端功能。
+
+**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。
+self-report 每个 cycle 的状态，不跳过任何阶段。
 </system-reminder>
 
 ## 工作流程

package/assets/agents/team/frontend.md

@@ -16,12 +16,26 @@ capabilities:
   push_branch: true
   approve_review: false
   complete_goal: false
+permission:
+  bash:
+    "*": "deny"
+    "npm *": "allow"
+    "git *": "allow"
+  edit:
+    "*": "deny"
+    ".worktree/**": "allow"
+    "src/**": "allow"
+    "test/**": "allow"
+    "assets/**": "allow"
 ---
 
 <system-reminder>
 你是团队中的 @frontend，负责前端代码实现。
 
 你接收 @architect 的技术方案，按任务逐一实现前端功能。
+
+**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。
+self-report 每个 cycle 的状态，不跳过任何阶段。
 </system-reminder>
 
 ## 工作流程

package/assets/agents/team/goal-verify.md

@@ -0,0 +1,54 @@
+---
+name: goal-verify
+description: Goal verification agent. Verifies completion independently.
+mode: subagent
+color: '#9c27b0'
+tools:
+  read: true
+  bash: true
+  write: false
+  edit: false
+permission:
+  bash:
+    "*": "deny"
+    "npm *": "allow"
+    "git status": "allow"
+    "git status *": "allow"
+    "git diff": "allow"
+    "git diff *": "allow"
+    "git log": "allow"
+    "git log *": "allow"
+  edit: "deny"
+---
+
+<system-reminder>
+你是 goal-verify，负责独立验证 Goal 是否已完全达成。
+
+你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、backend、frontend、architect）无权完成 Goal。
+
+你需要从空白上下文开始 — 不假设之前的工作已完成。
+</system-reminder>
+
+## 职责
+
+唯一职责：检查 Goal 是否已完全达成。
+
+先调用 `goal({op:"get"})` 获取 objective 和 completion criterion。
+
+---
+
+## 验证流程
+
+1. 调用 `goal({op:"get"})` 获取 objective 和 completion criterion。
+2. 拆解为具体的、逐项可检查的需求。
+3. 对每个需求收集证据：
+   - 阅读完整文件 — 不只看摘要
+   - 运行测试、构建、lint
+   - 检查 imports、exports、类型是否正确
+4. 每项结论分类：SATISFIED / NOT SATISFIED / UNCERTAIN
+5. 全部 SATISFIED → 调用 `goal({op:"complete"})`
+6. 任何 NOT SATISFIED / UNCERTAIN → 不调用 complete，返回详细报告
+
+---
+
+不创建或修改任何文件。你是只读验证者。

package/assets/agents/team/reviewer.md

@@ -16,6 +16,16 @@ capabilities:
   push_branch: false
   approve_review: false
   complete_goal: false
+permission:
+  bash:
+    "*": "deny"
+    "gh pr view": "allow"
+    "gh pr view *": "allow"
+    "diff": "allow"
+    "diff *": "allow"
+    "gh pr checks": "allow"
+    "gh pr checks *": "allow"
+  edit: "deny"
 ---
 
 <system-reminder>

package/assets/skills/flow-code/SKILL.md

@@ -67,6 +67,19 @@ npm install
 npm test
 ```
 
+#### TDD Advisory Protocol
+
+编码阶段必须遵循 `flow-tdd` skill 定义的 TDD 流程。Agent 在编写任何功能代码前加载 `flow-tdd` skill。
+
+**TDD 检查点（commit 前自检）：**
+- [ ] 每个功能的代码变更都有对应的测试
+- [ ] 测试在修改前是 RED（失败），修改后是 GREEN（通过）
+- [ ] 已完成 `final-regression`（全部测试通过）
+- [ ] 已完成 `final-verification`（对照 acceptance_criteria）
+- [ ] self-report 已写入 commit message 或 PR body
+
+> 引用：`flow-tdd` skill 是 TDD 协议的唯一来源，包含完整的 RED→GREEN cycle 状态机、abandon-cycle 规则和 final-regression/verification 流程。
+
 ### 6. 文档同步检查
 完成编码后，逐项检查以下文档是否需要同步更新：
 

package/assets/skills/flow-review/SKILL.md

@@ -39,6 +39,13 @@ gh pr view <pr-number> --json title,body,files
 对照 PRD（`docs/prd/`）和设计方案（`docs/dev/specs/`）验证。
 - 如发现实现与设计偏差 → 追加到 `docs/dev/changelog/<YYYY-MM-DD-NNN-slug>.md`
 
+**TDD Criterion Coverage** — 检查 Task 的 `acceptance_criteria` 是否被 PR 覆盖：
+- 对照 Task frontmatter 中的 `acceptance` 数组，逐条核查
+- 检查 PR 是否包含每条 criterion 对应的测试或验证
+- 检查 `tdd` 配置块中的 `mode` 和 `min_cycles` 是否被遵循
+- **明确不检查 commit order** — TDD cycle 的 RED→GREEN 顺序是编码过程约束，
+  reviewer 不审查 commit 历史是否呈现 RED-first 模式
+
 ### 5. 合并前检查
 在合并前确认以下项：
 - 文档同步已完成（`docs/guides/` 已更新或无需更新）

package/assets/skills/flow-tasks/SKILL.md

@@ -41,7 +41,39 @@ name: "<task-name>"
 depends_on: ["<前置任务>"]
 labels: ["backend"]
 worktree_root: ".worktree/<task-name>/"
+test_commands:
+  - "npm test -- <test-file>"
+  - "npm run typecheck"
+verify_commands:
+  - "npm run lint"
+tdd:
+  mode: strict
+  min_cycles: 1
+acceptance:
+  - criteria: "<验收标准描述>"
+    verification_type: test | manual | lint
+    test_command: "<关联的测试命令>"
+  - criteria: "<另一条验收标准>"
+    verification_type: test
+    test_command: "npm test -- <other-test>"
 ---
+```
+
+Task frontmatter 新增字段说明：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `test_commands` | `string[]` | TDD cycle 中运行的测试命令列表 |
+| `verify_commands` | `string[]` | final-verification 阶段运行的验证命令 |
+| `tdd.mode` | `"strict" \| "advisory"` | TDD 模式，默认 `strict` |
+| `tdd.min_cycles` | `number` | 最少 RED→GREEN cycle 数量，默认 `1` |
+| `acceptance` | `object[]` | 结构化验收标准列表 |
+| `acceptance[].criteria` | `string` | 验收标准描述 |
+| `acceptance[].verification_type` | `"test" \| "manual" \| "lint"` | 验证方式 |
+| `acceptance[].test_command` | `string` | 关联的测试命令（verification_type 为 test 时必填） |
+
+`tdd` 配置块为 `flow-tdd` skill 提供运行时参数。模式默认 `strict`，
+表示 Agent 必须遵循 RED→GREEN→final-regression→final-verification 完整流程。
 
 ## 目标
 
@@ -49,6 +81,16 @@ worktree_root: ".worktree/<task-name>/"
 
 ## 验收标准
 
+验收标准以结构化 `acceptance` 数组形式定义在 frontmatter 中（见上方模板）。
+每条标准包含 `criteria`（描述）、`verification_type`（验证方式）和 `test_command`（关联命令）。
+`flow-tdd` skill 在 final-verification 阶段逐条核验这些标准。
+
+## TDD 集成
+
+本 skill 生成的 `test_commands`、`verify_commands`、`tdd` 配置块和 `acceptance_criteria`
+是 `flow-tdd` skill 的输入。`flow-tdd` 根据这些字段执行 RED→GREEN cycle、
+final-regression 和 final-verification。
+
 ## Worktree
 - 路径: `.worktree/<task-name>/`
 - 分支: `feat/<task-name>`

package/assets/skills/flow-tdd/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: flow-tdd
+description: TDD Prompt 协议 — Phase A Advisory 层，定义 RED→GREEN self-reported 流程
+---
+
+# flow-tdd
+
+TDD（Test-Driven Development）Prompt 协议，为所有编码阶段提供统一的 TDD 流程约束。
+本 skill 是 TDD 协议的唯一来源，其他 skills 和 agents 通过引用本协议获得一致的 TDD 行为。
+
+## Advisory Procedure
+
+Phase A Advisory 层协议：Agent 自行遵循 TDD 流程并 self-report 状态，无需工具拦截。
+
+### Cycle 状态机
+
+```
+            ┌─────────────┐
+            │ cycle-start │ ← 开始新的 TDD 循环
+            └──────┬──────┘
+                   │
+                   ▼
+            ┌─────────────┐
+            │    red      │ ← 编写/更新测试，验证测试失败（RED）
+            └──────┬──────┘
+                   │
+                   ▼
+            ┌─────────────┐
+            │   green     │ ← 最小实现使测试通过（GREEN），可在此阶段重构
+            └──────┬──────┘
+                   │
+        ┌──────────┼──────────┐
+        ▼          ▼          ▼
+   ┌─────────┐ ┌─────────┐ ┌──────────────┐
+   │ 下一个   │ │ abandon │ │ 所有 cycle   │
+   │ cycle   │ │ -cycle  │ │ 完成         │
+   └─────────┘ └─────────┘ └──────┬───────┘
+                                  │
+                                  ▼
+                          ┌──────────────────┐
+                          │ final-regression │ ← 运行全部测试，确认无回归
+                          └────────┬─────────┘
+                                   │
+                                   ▼
+                          ┌───────────────────┐
+                          │ final-verification│ ← 对照 acceptance_criteria 逐条验证
+                          └───────────────────┘
+```
+
+### cycle-start
+
+开始一个新的 RED→GREEN 循环。Agent 在开始实现前声明当前 cycle 的目标（要实现的测试/功能）。
+
+**self-report 格式：**
+```
+## TDD cycle-start
+- cycle: <序号>
+- target: <本 cycle 要实现的功能/测试描述>
+```
+
+### red
+
+编写或更新测试用例，验证测试在当前实现下失败。
+
+**约束：**
+- 测试必须有明确的 fail/pass 边界
+- 测试运行命令必须与 `test_commands` 中定义的一致
+- 记录测试失败输出作为 RED evidence
+
+**self-report 格式：**
+```
+## TDD red
+- test: <测试名称>
+- command: <运行命令>
+- result: FAIL（预期）
+```
+
+### green
+
+编写最小实现使 RED 阶段编写的测试通过。可在此阶段进行局部重构（消除重复、改善命名等），但不应扩展范围。
+
+**约束：**
+- 只写使当前测试通过的最少代码
+- 不新增与当前 test 无关的功能
+- 重构仅限于当前 cycle 涉及的代码
+
+**self-report 格式：**
+```
+## TDD green
+- test: <测试名称>
+- command: <运行命令>
+- result: PASS
+- changes: <涉及的文件列表>
+```
+
+### abandon-cycle
+
+当发现当前 cycle 的目标不合理、设计有缺陷或需要回退时，废弃当前 cycle 的所有修改。
+
+**触发条件：**
+- RED 阶段发现测试设计有误
+- GREEN 阶段发现需要根本性重新设计
+- 发现更简单的替代方案
+
+**流程：**
+1. 放弃当前 cycle 的修改（`git checkout -- <files>` 或 `git stash drop`）
+2. 记录 abandon 原因
+3. 重新从 cycle-start 开始
+
+**self-report 格式：**
+```
+## TDD abandon-cycle
+- cycle: <序号>
+- reason: <废弃原因>
+```
+
+### final-regression
+
+所有 cycle 完成后，运行项目全部测试套件，确认无回归。
+
+**约束：**
+- 必须运行 `test_commands` 中定义的全部命令
+- 所有测试必须通过
+- 如有失败 → 修复（不要求新 cycle，但需记录修复内容）
+
+**self-report 格式：**
+```
+## TDD final-regression
+- passed: <通过的测试数>
+- failed: <失败的测试数>
+- total: <测试总数>
+```
+
+### final-verification
+
+对照 Task 的 `acceptance_criteria` 逐条验证，确认全部满足。
+
+**self-report 格式：**
+```
+## TDD final-verification
+- criteria_total: <总数>
+- criteria_met: <已满足>
+- criteria_pending: <未满足>
+```
+
+## Runtime Procedure
+
+> **Phase C 启用** — 以下为 Runtime Enforcement 协议占位，当前阶段不生效。
+>
+> Phase C 将引入 `tdd_checkpoint` 工具在运行时拦截 RED/GREEN 状态切换，
+> 并将 evidence 写入 FlowRun 存储。Agent 不直接调用这些工具的时机和方式
+> 由 Phase C 的 `tdd_checkpoint` 工具实现决定。
+
+<!--
+Phase C 启用后的 Runtime Procedure:
+1. cycle-start → tdd_checkpoint({ stage: "cycle-start", task_id })
+2. red → tdd_checkpoint({ stage: "red", evidence: test_output, task_id })
+3. green → tdd_checkpoint({ stage: "green", evidence: test_output, task_id })
+4. abandon-cycle → tdd_checkpoint({ stage: "abandon-cycle", reason, task_id })
+5. final-regression → tdd_checkpoint({ stage: "final-regression", evidence: full_test_output, task_id })
+6. final-verification → tdd_checkpoint({ stage: "final-verification", evidence: criteria_checklist, task_id })
+-->
+
+## Contract
+
+### Trigger
+由编码阶段（`flow-code`）自动触发。Agent 在开始编码任务时加载 `flow-tdd` skill 获取 TDD 流程约束。
+
+### Inputs
+- Task 定义中的 `acceptance_criteria`（来源：`flow-tasks` 产出）
+- Task 定义中的 `test_commands`（来源：`flow-tasks` 产出）
+- Task 定义中的 `verify_commands`（来源：`flow-tasks` 产出）
+- Task 定义中的 `tdd` 配置块 — `mode`（`strict`/`advisory`）、`min_cycles`（来源：`flow-tasks` 产出）
+
+### Preconditions
+- Task 文件存在，包含 `acceptance_criteria`、`test_commands`、`tdd` 配置块
+- 测试运行环境就绪（`npm install` 已完成）
+
+### Procedure
+1. 读取 Task 的 `acceptance_criteria`、`test_commands`、`verify_commands`
+2. **Advisory Mode**：为每个验收标准识别对应的测试用例
+3. 执行 `cycle-start` → 声明当前 cycle 目标
+4. 执行 `red` → 编写测试，验证失败
+5. 执行 `green` → 最小实现，验证通过
+6. 重复 cycle 直到所有 criterion 覆盖
+7. 执行 `final-regression` → 运行全部测试
+8. 执行 `final-verification` → 逐条对照 acceptance_criteria
+
+### Outputs
+- 每个 cycle 的 self-report（提交到 commit message 或 PR body）
+- `final-regression` 报告（测试通过/失败统计）
+- `final-verification` 报告（criterion 覆盖情况）
+
+### Failure
+- RED 阶段测试意外通过 → 检查测试是否有意义，可能需要 abandon-cycle
+- GREEN 阶段测试持续失败 → 检查实现逻辑，记录失败原因
+- final-regression 失败 → 修复回归，不要求新 cycle
+- final-verification 未全部满足 → 返回未完成的 criterion，补充 cycle
+
+### Idempotency
+- 同一 cycle 重复执行 → 以最后一次结果为准
+- final-regression 重复执行 → 覆盖上次结果
+
+### Prohibited Actions
+- 不跳过 RED 阶段直接进入 GREEN
+- 不跳过 final-regression 直接 commit
+- 不在 abandon-cycle 后保留修改
+- 不修改 `tdd` 配置块中的 `mode` 和 `min_cycles` 值

package/dist/flowrun/adapter.d.ts

@@ -0,0 +1,49 @@
+import type { TddRunnerPolicy, TddCommandEvidence, TddFailureKind } from "./types.js";
+export interface VitestOutput {
+    exitCode: number | null;
+    testsCollected: number | null;
+    testsFailed: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/** classifyVitestFailure 的输入 */
+export interface FailureInput {
+    exitCode: number | null;
+    testsCollected: number | null;
+    testsFailed: number | null;
+    stderr: string;
+    timedOut?: boolean;
+}
+/**
+ * 校验 test selector 语法安全。
+ * 拒绝 shell 元字符、命令替换、换行等。
+ */
+export declare function validateSelector(selector: string): void;
+/**
+ * 将 baseCommand 字符串解析为 argv 数组并附加 selector。
+ */
+export declare function buildVitestArgs(policy: TddRunnerPolicy, selector: string): string[];
+/**
+ * 执行 vitest 命令并捕获输出。
+ */
+export declare function executeVitest(args: string[], cwd: string, timeoutMs: number): Promise<VitestOutput>;
+/**
+ * 根据 vitest 输出分类失败类型。
+ *
+ * 规则：
+ * - timeout → "timeout"
+ * - 成功启动 + 收集测试 + assertion 失败 → "assertion"（RED）
+ * - 成功启动 + 目标代码不存在 → "missing-behavior"（RED）
+ * - config/transform/dep 错误 → "infrastructure"
+ * - 零测试收集 → "infrastructure"
+ */
+export declare function classifyVitestFailure(input: FailureInput): TddFailureKind | null;
+/**
+ * 执行 RED check：运行 vitest focused test，返回 TddCommandEvidence。
+ *
+ * @param policy - TDD runner policy（含 baseCommand、timeoutMs 等）
+ * @param selector - focused test selector（文件路径或 vitest flag）
+ * @param cwd - 工作目录
+ */
+export declare function executeRedCheck(policy: TddRunnerPolicy, selector: string, cwd: string): Promise<TddCommandEvidence>;