@devcxl/opencode-cabbage 1.1.0 → 1.3.0

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

@@ -1,41 +1,46 @@
 ---
 name: flow-setup
-description: 初始化 — 探测环境 → 生成 workflow → 确认 Profile
+description: 初始化 — 探测环境 → 确认 Profile
 ---
 
 # flow-setup
 
-初始化阶段：探测开发环境、生成缺失的 CI/release workflow、确认 AGENTS.md Project Profile。
-所有探测与写入由内核工具 `setup_control` 完成，本 skill 只定义流程，不复制工具实现。
+初始化阶段：探测开发环境、确认 AGENTS.md Project Profile。
+纯 Prompt 流程：直接使用 git/gh 命令探测，Profile 由用户确认后写入根 AGENTS.md。
 
-## 核心：调用 setup_control
+## 核心流程
 
-调用 `setup_control` 完成三个阶段：
+1. **探测环境**
+   ```bash
+   gh auth status                        # gh CLI 认证
+   gh repo view --json nameWithOwner,defaultBranchRef  # 仓库与默认分支
+   ls .github/workflows/                 # 现有 CI/release workflow
+   ```
 
-1. `setup_control{op:"probe"}` — 探测 git/gh/CI/Profile，输出 readiness 报告
-2. `setup_control{op:"generate-workflows"}` — 缺失时生成 CI/release workflow 草案 + Setup PR（人工合入）
-3. `setup_control{op:"confirm-profile"}` — 用户确认后将 Profile 区块写入根 AGENTS.md
+2. **确认 Project Profile**：向用户逐项确认以下配置（技术栈无关）：
+   - test command：测试命令（如 `npm test`）
+   - regression command：全量回归命令
+   - test file patterns：测试文件匹配（如 `test/**/*.test.ts`）
+   - implementation file patterns：实现文件匹配（如 `src/**/*.ts`）
+   - version bump rule、version file、tag format、release workflow
 
-Profile 区块格式（内核解析白名单，§9.1）：
+3. **写入根 AGENTS.md**：用户确认后，将 Profile 区块追加/替换到根 `AGENTS.md`：
 
 ```markdown
 ## Project Profile
 
-- test command: `npm test -- run`
+- test command: `npm test`
+- regression command: `npm test`
 - test file patterns: `test/**/*.test.ts`
 - implementation file patterns: `src/**/*.ts`
-- tdd default mode: `strict`
 - version bump rule: `breaking→major, feature→minor, fix→patch`
 - version file: `package.json`
 - tag format: `v{version}`
 - release workflow: `.github/workflows/release.yml`
 ```
 
-未确认 Profile 时 `flow_control{op:"create-flow"}` 会阻断并提示先执行 `/setup`。
-
 ## Output
-- readiness 报告（development-ready / release-ready 逐项布尔）
-- `.github/workflows/` 草案（缺失时，经 Setup PR 人工合入）
+- readiness 报告（git/gh 可用性、CI/release workflow 存在性）
 - 根 AGENTS.md `## Project Profile` 区块
 
 ## Contract
@@ -50,23 +55,21 @@ Profile 区块格式（内核解析白名单，§9.1）：
 - gh CLI 已认证（宿主 `gh auth`）
 
 ### Procedure
-1. 调用 `setup_control{op:"probe"}` 读取 readiness 报告
-2. 缺失 workflow 时调用 `setup_control{op:"generate-workflows"}` 生成草案
-3. 用户确认后调用 `setup_control{op:"confirm-profile"}` 写入 Profile
+1. 用 gh/git 命令探测环境，输出 readiness 报告
+2. 缺失 CI/release workflow 时提示用户（可手工创建）
+3. 向用户逐项确认 Profile 配置
+4. 用户确认后写入根 AGENTS.md Profile 区块
 
 ### Outputs
 - readiness 报告
-- workflow 草案（可选）
 - 根 AGENTS.md Profile 区块
 
 ### Failure
 - gh auth 失败 → 提示用户执行 `gh auth login` 后重试
-- workflow 生成失败 → 报告错误并停止
 
 ### Idempotency
-- Profile 已确认 → 重复 confirm 覆盖写入（工具内读后写）
-- workflow 已存在 → 跳过生成
+- Profile 已存在 → 覆盖为最新确认值
 
 ### Prohibited Actions
-- 不手工编辑 AGENTS.md Profile 区块（由 setup_control 写回）
-- 不直接 push 或创建 Setup PR（工具内部执行）
+- 不写入未获用户确认的 Profile 项
+- 不假设测试命令为 npm（按用户确认的技术栈）

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

@@ -1,77 +1,220 @@
 ---
 name: flow-tasks
-description: DAG 任务拆解 → Task Record（task_control）
+description: 将技术方案拆解为可独立实现的 tracer-bullet Task Plan 与 DAG
 ---
 
 # flow-tasks
 
-将设计方案拆解为 DAG（有向无环图）任务，并用 `task_control{op:"create-task"}` 创建 Task Record（GitHub Sub Issue）。
+将设计方案拆解为 Task Plan 与 DAG（有向无环图）。每个 Task 都是一条完整但狭窄的行为切片，可以交给一个 fresh-context developer agent 独立实现和验证。
 
-## 核心：调用 task_control
+本 skill 只定义任务拆解与 Task Plan 产出。`@architect` 不创建 GitHub Issue、不操作 GitHub lifecycle；调用方负责检查并发布 Task Plan。
 
-`task_control{op:"create-task", title:"<英文功能标题>", acceptance_criteria:"<JSON>", ...}` 创建 Sub Issue。
-内核负责 slug 派生与校验、标题规范（R3）、关联 Parent Issue——创建动作全部收敛到工具内。
+## Task 拆解规则
 
-## DAG 拆解
+每个 Task 必须：
 
-#### 拆解前自检
+1. 交付一个可以观察或验证的新行为。
+2. 是垂直切片，而不是 Controller / Service / DAO 等技术分层。
+3. 可以交给一个 fresh-context developer agent 独立理解和实现。
+4. 完成以后仓库处于可工作的状态，而不是为下一个 Task 留空壳。
+5. `Blocked By` 只声明“前者未完成时，本 Task 无法开始”的真实阻塞关系。
 
-1. **能否用一个任务完成？** — 如果功能足够内聚，不强拆多个任务
-2. **拆开后能否独立验证？** — 每个任务必须有独立的验收标准
-3. **拆开后耦合是否最低？** — 两个任务共享大量数据结构/模块 → 合并
+每个 Task 应适合一个 fresh-context developer agent：
 
-#### 反模式
+- 不需要读取整个 Flow 历史才能理解。
+- Task、Design 与 repository context 足够开始工作。
+- 正常情况下不需要再次进行架构设计。
+- 可以在一次独立开发循环中实现、测试、提交。
+
+## 何时拆分
+
+不要为了制造并行度而拆 Task。
+
+如果一个行为高度内聚、修改范围集中、一个 fresh context 可以完成，且没有独立可验证的中间行为，则保持为一个 Task。
+
+如果一个 Task 同时包含三个以上相互独立的“用户可以……”行为，应考虑按这些可独立验证的行为拆分。
+
+拆分前检查：
+
+1. **能否用一个 Task 完成？** — 足够内聚时不强拆。
+2. **拆开后能否独立验证？** — 每个 Task 都必须交付可观察行为。
+3. **是否真的阻塞？** — 只有无法开始的前置关系才进入 DAG。
+4. **拆开后耦合是否更低？** — 大量共享同一数据结构或模块时优先合并。
+
+## Behavior-preserving Pre-refactor
+
+行为 Task 的唯一例外是必要的 behavior-preserving pre-refactor：当现有结构使后续行为无法在一个可测试、可工作的垂直切片中安全实现时，可以先建立一个重构 Task。
+
+Pre-refactor 必须同时满足：
+
+- 不改变现有可观察行为，并用回归验证证明行为保持。
+- 自身完成后仓库保持可工作，不留下迁移一半的状态。
+- 只消除阻碍后续行为的具体结构问题，不搭通用框架、不预留未来扩展点。
+- 后续行为确实无法安全开始时，才将 pre-refactor 声明为 blocking edge。
+
+仅仅“这样更整洁”或“以后可能复用”不构成 pre-refactor。优先直接交付行为切片。
+
+Pre-refactor 的 `Builds` 应说明“保持哪个现有行为不变，并消除哪个阻碍后续行为的具体结构问题”，不能写成文件或类的修改清单。
+
+## 反模式
 
 | 反模式 | 示例 | 正确做法 |
 |--------|------|----------|
-| 技术分层拆分 | "建表任务" → "DAO 任务" → "Service 任务" | 垂直切片：一个任务包含完整链路 |
-| 过度拆分 | 一个 CRUD 拆成四个任务 | 一个 CRUD 就是一个任务 |
-| 预留式拆分 | "先搭框架，后面任务再填内容" | 不要有空壳任务 |
+| 技术分层拆分 | `create-session-table` → `implement-session-service` → `implement-session-api` | `create-and-restore-session` |
+| 测试单独成 Task | `add-session-tests` | 测试随行为切片一起交付 |
+| 过度拆分 | 一个内聚 CRUD 拆成多个 Task | 保持为一个可独立验证的 Task |
+| 预留式拆分 | 先搭框架，后续 Task 再填内容 | 每个 Task 完成后仓库都可工作 |
+| 虚假依赖 | 因修改相邻文件而声明依赖 | 仅声明不完成前者就无法开始的依赖 |
+
+## Task 定义
+
+每个 Task 保存为 `docs/dev/tasks/<task-name>.md`，是 developer 使用的 **Agent Implementation Contract**：
+
+`task-name` 使用简短的英文 kebab-case 行为短语，并作为后续 `feat/<task-name>` 分支名的基准。
+
+```markdown
+---
+issue: null
+test_commands:
+  - <targeted test command>
+verify_commands:
+  - <verification command>
+---
+
+# <task-slug>
+
+## Builds
+
+<这个 Task 完成后，哪个端到端行为真正可以工作？>
+
+## Acceptance Criteria
+
+- [ ] <可观察行为>
+- [ ] <边界或异常行为>
+- [ ] <回归要求>
+
+## Blocked By
 
-DAG 使用 Mermaid 语法绘制，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
+- <blocking-task-slug>
+- 或 None
 
-## 任务定义文件
+## Implementation Notes
 
-每个任务一个文件 `docs/dev/tasks/<task-name>.md`，frontmatter 含 `test_commands` / `verify_commands` / `tdd` 配置块 / `acceptance` 结构化验收标准。
-这些字段是 `flow-tdd` skill 的输入（RED→GREEN cycle、final-regression、final-verification）。
+<只记录真正限制实现方式的重要设计决策；不要复制具体实现步骤。>
+```
+
+`Builds` 必须直接说明完成后的可工作行为。`Acceptance Criteria` 是 `flow-tdd` 使用的行为规格；`test_commands` 与 `verify_commands` 只放在 Task 文件中。
+
+Task 的行为测试必须沿用 Design `Testing Decisions` 中约定的 Test Seam。Task 不重新设计 Seam；如果既有 Seam 无法验证该行为，应返回 Design Gap，由调用方在当前 stage 完成 amendment。
+
+### Design Gap
+
+存量 Design 缺少 `Testing Decisions` 时，不回退 lifecycle stage，也不生成半成品 Task Plan。返回给调用方：
+
+```markdown
+## Design Gap
+
+- Current Stage: tasks
+- Design File: <docs/dev/specs/...>
+- Missing Behaviors:
+  - <缺少 Test Seam 或 Observable Result 的行为>
+- Existing Context: <已发现的公共 Interface 与测试惯例；没有则写 None>
+- Required Amendment: 为以上行为补充 Testing Decisions
+```
+
+调用方在当前 tasks 阶段完成 Design Amendment 后，重新执行 Task Planning。`@architect` 不在 flow-tasks 内自行修改测试设计。
+
+规划阶段尚无 Issue 编号，`Blocked By` 使用 task slug。发布后由调用方将其更新为真实 `#<issue-number>`；无依赖时写 `None`。
+
+## DAG
+
+DAG 使用 Mermaid 语法，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
+
+- 节点对应行为 Task，不对应技术层。
+- 边只表示真实 blocking edge。
+- 发布前必须检查环形依赖。
+- 发布后将 Task 节点与依赖更新为真实 Issue 编号。
+
+## GitHub 发布边界
+
+GitHub Sub Issue 是协作与生命周期记录，正文只提取 Task 中用户可读的内容：
+
+```markdown
+## Builds
+
+...
+
+## Acceptance Criteria
+
+- [ ] ...
+
+## Blocked By
+
+None
+```
+
+不得把 `issue`、`test_commands`、`verify_commands` 或内部实现说明复制到 GitHub Issue。
+
+发布由调用方执行：
+
+- 普通 Flow：`@dev-lifecycle` 检查后自动发布。
+- 高风险 Flow：展示 Task Plan，用户确认后发布。
+- 用户主动 `/tasks`：展示 Task Plan，等待用户确认后发布。
+- `@architect`：产出并返回 Task Plan 后停止，不执行发布。
 
 ## Output
-- `docs/dev/tasks/*.md` — 独立任务文件
-- GitHub Sub Issues（由 task_control 创建，依赖关系在 body 中声明）
+
+- `docs/dev/tasks/*.md` — Agent Implementation Contracts
+- `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md` — Task DAG
+- 返回给调用方的 Task Plan 摘要与拓扑顺序
 
 ## 后续
-- **/code** — 认领 Sub Issue 开始编码
+
+- `@dev-lifecycle` 检查并发布 GitHub Sub Issues
+- **/code** — 按 Task DAG 进入编码阶段
 
 ## Contract
 
 ### Trigger
-由 `/tasks` 命令或 `@dev-lifecycle` Phase 2 触发。
+由 `/tasks` 命令或 `@dev-lifecycle` Phase 2 委派 `@architect` 触发。
 
 ### Inputs
 - `docs/dev/specs/<title>.md` — 技术方案
-- Flow Record 编号
+- 相关 PRD 与 ADR
+- Parent Issue 编号
 
 ### Preconditions
-- `/design` 已完成 → 技术方案和 ADR 存在（Planning Baseline 已合入）
+- `/design` 已完成，技术方案和 ADR 存在
 
 ### Procedure
-1. 基于技术方案拆解 DAG（Mermaid 图 + 任务文件）
-2. 为每个任务调用 `task_control{op:"create-task"}` 创建 Sub Issue
-3. 任务文件随 Planning PR 合入默认分支
+1. 读取设计基线与必要的 repository context。
+2. 读取 Design `Testing Decisions`，确认关键行为已有公共 Test Seam；缺失时返回 Design Gap 并停止，不生成或更新 Task 文件。
+3. 识别可独立验证的 tracer-bullet 行为切片；仅在必要时增加 behavior-preserving pre-refactor。
+4. 为每个 Task 定义 `Builds`、`Acceptance Criteria`、`Blocked By` 与必要的 `Implementation Notes`。
+5. 生成 Task 文件与 Mermaid DAG。
+6. 检查技术分层式拆分、空壳 Task、虚假依赖、臆测性 pre-refactor 与环形依赖。
+7. 返回 Task Plan、文件路径与拓扑顺序；不创建 GitHub Issue。
 
 ### Outputs
-- `docs/dev/tasks/<feature-slug>/` — DAG 与任务文件
-- GitHub Sub Issues（含依赖声明）
+- Task 定义文件
+- Task DAG
+- 供调用方检查与发布的 Task Plan
+- 或结构化 Design Gap（存量 Design 缺少 Testing Decisions 时）
 
 ### Failure
+- 无法从设计中确定可验证行为 → 暂停并指出缺失信息
+- Design Amendment 后仍缺少稳定 Test Seam → 报告未解决的 Design Gap，由调用方暂停当前阶段
 - DAG 存在环形依赖 → 阻止并报告
-- Sub Issue 创建失败 → 记录失败项
+- Task 无法由 fresh-context developer 独立理解 → 重新拆分或补足契约
 
 ### Idempotency
-- 任务文件已存在 → 读取并更新
-- Sub Issue 已创建 → 内核检测同名冲突（未合并分支/worktree）并拒绝
+- Task 文件已存在 → 读取并更新，不创建重复定义
+- 已有 `issue` 编号 → 保留并交给调用方核验，不重复发布
 
 ### Prohibited Actions
-- 不跳过 DAG 依赖检查
-- 不绕过 task_control 手工创建 Sub Issue（由 create-task 完成）
-- 不直接 push 到默认分支
+- 不按技术层拆分 Task
+- 不为制造并行度而拆分 Task
+- 不创建完成后不可工作的空壳 Task
+- 不用 pre-refactor 包装搭框架、清理代码或预留扩展点
+- 不把非阻塞关系写入 `Blocked By`
+- `@architect` 不执行 `gh issue create`、`git push`、PR、merge 或 worktree 操作

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

@@ -1,6 +1,6 @@
 ---
 name: flow-tdd
-description: TDD Prompt 协议 — RED→GREEN 状态机 + tdd_checkpoint Runtime 证据
+description: 公共 Test Seam 上的行为 TDD — RED→GREEN 状态机 + self-report 证据
 ---
 
 # flow-tdd
@@ -8,9 +8,44 @@ description: TDD Prompt 协议 — RED→GREEN 状态机 + tdd_checkpoint Runtim
 TDD（Test-Driven Development）Prompt 协议，为所有编码阶段提供统一的 TDD 流程约束。
 本 skill 是 TDD 协议的唯一来源，其他 skills 和 agents 通过引用本协议获得一致的 TDD 行为。
 
+## 核心原则
+
+测试是行为规格：通过 Design `Testing Decisions` 约定的公共 Test Seam 验证可观察行为，而不是验证内部实现。只要公共行为不变，重构 Module 内部实现不应导致测试失败。
+
+每个 TDD cycle 是一个最窄行为切片：
+
+```text
+确定 Test Seam 与一个行为
+        ↓
+写一个行为测试
+        ↓
+RED
+        ↓
+最小实现
+        ↓
+GREEN
+        ↓
+下一个行为
+```
+
+### 好测试
+
+- 名称描述调用者或用户可以完成什么，而不是调用了哪个内部方法。
+- 只通过约定的公共 Test Seam 触发并观察行为。
+- 期望值来自 Acceptance Criteria、已知正确示例或其他独立来源。
+- 实现重构但行为不变时仍然通过。
+
+### 反模式
+
+- **实现耦合** — 测试私有方法、内部协作对象、调用次数或调用顺序。
+- **侧信道验证** — 绕过公共 Seam 读取数据库或内部状态来证明行为。
+- **循环论证** — 用与实现相同的算法重新计算期望值。
+- **水平批量** — 先写完全部测试再实现；应按一个行为测试 → 一个最小实现逐次推进。
+- **为 mock 造抽象** — 仅允许在真实系统边界按既有 Interface 替换外部依赖，不为测试方便新增生产 Seam。
+
 ## Advisory Procedure
 
-Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过 `tdd_checkpoint` 提交证据。
+Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI 把关，内核不强制证据。
 
 ### Cycle 状态机
 
@@ -26,7 +61,7 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
                    │
                    ▼
             ┌─────────────┐
-            │   green     │ ← 最小实现使测试通过（GREEN），可在此阶段重构
+            │   green     │ ← 最小实现使测试通过（GREEN），仅做局部行为保持整理
             └──────┬──────┘
                    │
         ┌──────────┼──────────┐
@@ -43,19 +78,21 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
                                    │
                                    ▼
                           ┌───────────────────┐
-                          │ final-verification│ ← 对照 acceptance_criteria 逐条验证
+                          │ final-verification│ ← 对照 Acceptance Criteria 逐条验证
                           └───────────────────┘
 ```
 
 ### cycle-start
 
-开始一个新的 RED→GREEN 循环。Agent 在开始实现前声明当前 cycle 的目标（要实现的测试/功能）。
+开始一个新的 RED→GREEN 循环。Agent 在实现前从 Design `Testing Decisions` 读取 Test Seam，并声明本 cycle 的一个可观察行为。
 
 **self-report 格式：**
 ```
 ## TDD cycle-start
 - cycle: <序号>
-- target: <本 cycle 要实现的功能/测试描述>
+- behavior: <本 cycle 要交付的可观察行为>
+- test_seam: <约定的公共 Test Seam>
+- test: <通过该 Seam 验证行为的测试名称>
 ```
 
 ### red
@@ -64,6 +101,8 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
 
 **约束：**
 - 测试必须有明确的 fail/pass 边界
+- 测试名称描述行为，且只通过 cycle-start 声明的 Test Seam 触发和观察结果
+- RED 必须因目标行为尚未实现而失败，不能把环境、语法或夹具错误当作证据
 - 测试运行命令必须与 Task 的 `test_commands` 中定义的一致
 - 记录测试失败输出作为 RED evidence
 
@@ -77,12 +116,13 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
 
 ### green
 
-编写最小实现使 RED 阶段编写的测试通过。可在此阶段进行局部重构（消除重复、改善命名等），但不应扩展范围。
+编写最小实现使 RED 阶段的行为测试通过。可进行局部、行为保持的整理，但不得改变约定的 Test Seam 或扩展范围。
 
 **约束：**
 - 只写使当前测试通过的最少代码
 - 不新增与当前 test 无关的功能
 - 重构仅限于当前 cycle 涉及的代码
+- 不为通过测试而暴露内部状态、增加仅供测试使用的生产接口或改成实现细节断言
 
 **self-report 格式：**
 ```
@@ -133,7 +173,7 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
 
 ### final-verification
 
-对照 Task 的 `acceptance_criteria` 逐条验证，确认全部满足。
+对照 Task 的 `Acceptance Criteria` 逐条验证，确认每项都由公共 Test Seam 上的行为测试或 `verify_commands` 证明。
 
 **self-report 格式：**
 ```
@@ -143,54 +183,40 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
 - criteria_pending: <未满足>
 ```
 
-## Runtime Procedure
-
-每个 stage 通过 `tdd_checkpoint` 提交证据到 Task Record 单个受控评论（marker 包裹，唯一证据源）。
-工具亲自执行测试，不接受内联 evidence；RED 有效性校验（失败分类 + 实现文件相对基线未变 + 输入未偷换）。
-
-| Stage | tdd_checkpoint op |
-|-------|-------------------|
-| cycle-start | `tdd_checkpoint{op:"cycle-start", task_id, criterion_id, test_paths, test_selector}` |
-| red | `tdd_checkpoint{op:"red", task_id, cycle_id, test_selector}` — 测试失败 + 实现文件未变 |
-| green | `tdd_checkpoint{op:"green", task_id, cycle_id, test_selector}` — 同 selector 通过 |
-| abandon-cycle | `tdd_checkpoint{op:"abandon-cycle", task_id, cycle_id, reason}` |
-| final-regression | `tdd_checkpoint{op:"final-regression", task_id}` — 全量测试通过 |
-| final-verification | `tdd_checkpoint{op:"final-verification", task_id}` — 每条 criterion 有 pass cycle |
-
-纯文档变更豁免：`tdd_checkpoint{op:"not-applicable"}`（仅 primary）；其他豁免须用户批准（`exempt-request`）。
-
 ## Contract
 
 ### Trigger
 由编码阶段（`flow-code`）自动触发。Agent 在开始编码任务时加载 `flow-tdd` skill 获取 TDD 流程约束。
 
 ### Inputs
-- Task Record 中的 `acceptance_criteria`（来源：`flow-tasks` 产出）
-- Task Record 中的 `test_commands`（来源：`flow-tasks` 产出）
-- Task Record 中的 `verify_commands`（来源：`flow-tasks` 产出）
-- Task Record 中的 `tdd` 配置块 — `mode`（`strict`/`advisory`）、`min_cycles`（来源：`flow-tasks` 产出）
+- Task 文件中的 `Builds` 与 `Acceptance Criteria`（来源：`flow-tasks`）
+- Task frontmatter 中的 `test_commands` 与 `verify_commands`
+- Design `Testing Decisions` 中约定的 Test Seam 与 Observable Result
 
 ### Preconditions
-- Task Record 存在，包含 `acceptance_criteria`、`test_commands`、`tdd` 配置块
+- Task 文件存在，包含 `Builds`、`Acceptance Criteria`、`test_commands`
+- Design 已为目标行为定义公共 Test Seam；存量 Design 缺失时先向 primary 返回 Design Gap，由兼容门在当前 stage 补齐
 - 测试运行环境就绪（worktree 内依赖已安装）
 
 ### Procedure
-1. 读取 Task 的 `acceptance_criteria`、`test_commands`、`verify_commands`
-2. 为每个验收标准识别对应的测试用例
-3. 执行 `cycle-start` → 声明当前 cycle 目标并调用 tdd_checkpoint
-4. 执行 `red` → 编写测试，验证失败，提交 evidence
-5. 执行 `green` → 最小实现，验证通过，提交 evidence
-6. 重复 cycle 直到所有 criterion 覆盖
-7. 执行 `final-regression` → 运行全部测试
-8. 执行 `final-verification` → 逐条对照 acceptance_criteria
+1. 读取 Task 的 `Builds`、`Acceptance Criteria`、`test_commands`、`verify_commands`。
+2. 读取 Design `Testing Decisions`，确认目标行为的 Test Seam 与 Observable Result。
+3. 选择一个尚未满足的行为，执行 `cycle-start` 声明 behavior、test_seam 与 test。
+4. 执行 `red` → 只写该行为测试，验证因行为缺失而失败，记录 self-report。
+5. 执行 `green` → 编写最小实现，验证通过，记录 self-report。
+6. 按一个行为切片一个 cycle 重复，直到所有 Acceptance Criteria 被覆盖。
+7. 执行 `final-regression` → 运行全部测试。
+8. 执行 `final-verification` → 通过 Test Seam 或 `verify_commands` 逐条验证 Acceptance Criteria。
 
 ### Outputs
-- 每个 cycle 的 self-report + tdd_checkpoint evidence（Task Record 评论）
+- 每个 cycle 的 self-report
 - `final-regression` 报告（测试通过/失败统计）
 - `final-verification` 报告（criterion 覆盖情况）
 
 ### Failure
 - RED 阶段测试意外通过 → 检查测试是否有意义，可能需要 abandon-cycle
+- RED 因环境、语法或夹具错误失败 → 修复测试基础设施，不能计为 RED evidence
+- 只能通过内部实现观察目标行为 → 停止编码并向 primary 返回 Design Gap，不自行修改 Design、不回退 lifecycle stage
 - GREEN 阶段测试持续失败 → 检查实现逻辑，记录失败原因
 - final-regression 失败 → 修复回归，不要求新 cycle
 - final-verification 未全部满足 → 返回未完成的 criterion，补充 cycle
@@ -201,7 +227,9 @@ Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过
 
 ### Prohibited Actions
 - 不跳过 RED 阶段直接进入 GREEN
+- 不测试私有方法、内部调用次数、内部调用顺序或未约定的侧信道
+- 不一次批量编写多个行为测试后再统一实现
+- 不为了 mock 或测试方便新增生产抽象
 - 不跳过 final-regression 直接 commit
 - 不在 abandon-cycle 后保留修改
-- 不修改 Task `tdd` 配置块中的 `mode` 和 `min_cycles` 值
-- 不伪造/内联 tdd_checkpoint evidence（工具亲自执行测试）
+- 不伪造测试结果（实际运行命令后再 self-report）

package/codex-skills/agent-architect/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: agent-architect
+description: 负责需求分析、架构设计、技术方案和 DAG 任务拆解
+---
+
+<system-reminder>
+你是团队中的 @agent-architect，负责架构设计和技术方案。
+
+你的输出直接指导 @agent-developer 实现。
+
+**技能归属**：本 agent 只加载 `flow-design`（技术设计）、`flow-tasks`（任务拆解）两个 skill；禁止加载其他 skill。
+
+## 工程原则（铁律）
+
+以下原则贯穿设计和实现的全链路，你设计的每个方案必须满足这些原则。
+
+### KISS（Keep It Simple, Stupid）
+选择能工作的最简单方案。如果两个方案都能满足 PRD，选更简单的。
+如果方案让你犹豫"是不是过度设计"——那就是。
+
+### YAGNI（You Ain't Gonna Need It）
+只设计当前 PRD 明确要求的功能。不做"将来可能需要"的扩展点、
+不预留"以后会用到"的抽象、不添加"万一需要"的模块。
+
+### DRY（Don't Repeat Yourself）
+相同逻辑出现 3 次以上才考虑抽象。2 次以内的重复是可以接受的，
+过早抽象比适度重复更有害。
+
+### SRP（Single Responsibility Principle）
+每个模块只有一个修改的理由。设计时确保模块边界清晰，职责不重叠。
+
+### 方案自检
+每个设计决策必须能回答以下问题：
+1. "为什么不用更简单的方案？" — 如果答案涉及"将来可能"，说明过度设计
+2. "这个模块是否只有一个修改的理由？" — 如果否，拆分
+3. "这个抽象是否至少有 2 个具体用例？" — 如果否，删除抽象
+4. "调用者和测试通过哪个 Seam 使用并验证行为？" — 如果只能观察内部实现，重新设计 Interface
+5. "复杂性是否隐藏在小 Interface 后面？" — 如果泄漏到多个调用者，深化 Module
+
+### 禁止事项
+- 禁止设计"万能框架"（一个模块试图解决所有问题）
+- 禁止为单一用例创建抽象层
+- 禁止为单个假设 Adapter 创建 Seam；优先复用已有 Interface
+- 禁止引入项目未使用的新技术栈（除非 PRD 明确要求）
+- 如果设计让你犹豫"是不是过度设计"——那就是
+</system-reminder>
+
+## 职责
+
+1. 技术方案 — 基于 PRD 输出完整技术方案（技术栈、架构、Module、Interface、数据模型、Testing Decisions）
+2. ADR — 记录关键架构决策
+3. Design Amendment — 收到存量 Design Gap 时，只补原技术方案缺失的 Testing Decisions，不回退 lifecycle stage
+4. Task Planning
+   - 基于技术方案生成 tracer-bullet Task Plan
+   - 每个 Task 描述可验证的端到端行为，并定义 Acceptance Criteria
+   - 只定义真实 blocking edge，输出 DAG 与拓扑顺序
+   - 将 Task 定义写入 `docs/dev/tasks/` 并返回 Task Plan
+   - 不创建 GitHub Issue，不操作 Task 的 GitHub lifecycle
+
+## 输出规范
+
+- 技术方案 → `docs/dev/specs/<title>.md`
+- ADR → `docs/adr/<date>-<slug>.md`
+- 任务定义 → `docs/dev/tasks/<task-name>.md`
+
+## 原则
+
+- 优先复用项目已有技术栈
+- 接口定义必须完整（请求参数、响应结构、错误码）
+- 为关键行为明确公共 Test Seam 和可观察结果，developer 不应在实现阶段重新设计测试边界
+- 优先设计小 Interface 背后的 deep Module，让复杂性保持局部
+- 每个 Task 应是垂直切片，适合一个 fresh-context developer agent 独立理解和完成
+- Task、Design 与 repository context 应足以开始实现，正常情况下不需要再次进行架构设计
+- 每个 Task 应能在一次独立开发循环中实现、测试、提交
+- 标注方案中的假设和不确定项
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。