@devcxl/opencode-cabbage 1.2.0 → 2.0.0

package/codex-skills/flow-requirements/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: flow-requirements
+description: 渐进式需求澄清 → PRD → Parent Issue
+---
+
+# flow-requirements
+
+通过渐进式需求澄清将松散想法凝固为 PRD，并创建 Parent Issue（Flow Record）作为后续阶段的权威来源。
+
+## 核心理念：战争迷雾（Fog of War）
+
+需求澄清不是一次性穷举——只定义**前沿**（当前可见的待决策问题），逐个解决，每解决一个迷雾推开一层，直到所有关键决策已定，PRD 自然成形。
+
+## Phase A：创建决策映射
+
+在 `docs/dev/decision-map.md` 创建映射，追踪所有待决策问题（Ticket 含 slug / Blocked by / Status / Type / Question / Answer）。初始只创建 2–4 个前沿 Ticket，不试图穷举。
+
+Ticket 类型：Grilling（与用户对话澄清）/ Research（查文档）/ Prototype（低保真验证）。
+Research 型 Ticket → 派发 `@agent-researcher` 加载 `flow-research` skill 产出调研文档后，据结论 resolved。
+
+## Phase B：渐进式解决
+
+- 每次只处理**一个**已解除阻塞的 Ticket；处理前 Claim（`Status: in-progress`）
+- Grilling 型：**一次只问一个问题**，每个问题给出推荐答案，沿决策树分支深入
+- 追问技巧："然后呢？"（第 3 层才触及本质）、"如果不做这个会怎样？"（验证优先级）、"谁来判断做对了？"（明确验收）
+- 解决后 `Status: resolved` 并记录 Answer；检查是否有新问题浮现 → 追加 Ticket
+- 循环直到所有前沿 Ticket 已 resolved
+
+## Phase C：凝固为 PRD
+
+从 Decision Map 的 Answer 提炼为 PRD，保存到 `docs/prd/<title>.md`。
+
+## Phase D：创建 Parent Issue
+
+用 gh 创建 Parent Issue（Flow Record），作为目标与验收标准的权威来源：
+
+```bash
+gh issue create --title "<英文功能标题>" --body "<目标 + 验收标准>"
+```
+
+标题使用英文功能短语（kebab-case），后续分支名、目录名以其为基准。
+
+## CONTEXT.md 术语发现
+
+需求澄清中发现的领域术语写入根 `CONTEXT.md`（术语权威）。发现新术语或冲突时暂停提问，用户确认后更新。
+
+## Output
+- `docs/dev/decision-map.md` — 决策映射（PRD 生成后可删除）
+- `docs/prd/<title>.md` — PRD
+- Parent Issue（Flow Record）
+
+## 下一阶段
+- **/design** — 基于 PRD 进行技术设计
+
+## Contract
+
+### Trigger
+由 `/requirements` 命令或 `@agent-dev-lifecycle` 触发。
+
+### Inputs
+- 用户提供的功能描述（来自消息文本）
+
+### Preconditions
+- gh CLI 可用
+
+### Procedure
+1. 锚定核心问题，创建 Decision Map
+2. 渐进式解决所有前沿 Ticket（Grilling / Research / Prototype）
+3. 迷雾推至足够远 → 凝固为 PRD
+4. 记录领域术语到 CONTEXT.md
+5. 用 gh issue create 创建 Parent Issue
+
+### Outputs
+- `docs/dev/decision-map.md`
+- `docs/prd/<title>.md`
+- Parent Issue
+
+### Failure
+- gh 未认证 → 提示用户 `gh auth login` 后重试
+- Issue 创建失败 → 记录错误，不阻塞 PRD 写入
+
+### Idempotency
+- Decision Map 已存在 → 从中断点继续
+- PRD 文件已存在 → 更新而非覆盖
+- Parent Issue 已创建 → 复用其编号而非重复创建
+
+### Prohibited Actions
+- 不跳过 Phase A 和 Phase B 直接输出 PRD
+- 不一次问多个问题
+- 不创建重复的 Parent Issue（复用已有编号）

package/codex-skills/flow-research/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: flow-research
+description: 调研/事实核查 — 迭代深化 + 一手来源评分 + 反方搜索 + 置信度 → 调研文档（由 @researcher 加载）
+---
+
+# flow-research
+
+针对调研问题系统性收集资料、验证来源、交叉对比，产出仅事实、带引用的调研文档。由独立子 agent `@researcher` 加载执行，可作为 Flow 的阶段，也可作为独立轻量路径。
+
+## 核心流程
+
+1. **理解任务**：辨明「真问题 vs 表象」、前置假设、输出形式与范围（技术/时间/地区/行业）。
+2. **制定计划**：拆成子问题，说明来源需求、关键项、预判信息偏差与迭代轮次。
+3. **迭代收集**（多轮深化）：
+   - 来源优先级：官方文档/标准 → 学术/白皮书 → GitHub/Release/Issue → 权威博客 → 行业媒体 → 社区（社区仅作辅助）。
+   - 一手来源：优先追溯原始出处；来源评分卡（权威性/一手性/时效性/独立性/可验证性，综合 ≤12 仅作辅助参考）。
+   - 时间标注：关键引用标注发布时间；超时效门槛（技术选型>1年、安全/合规>6月、商业数据>1年、学术>3年）明确警告。
+4. **反方搜索 + 遗漏检查**：主动找反方观点、失败案例、替代方案隐藏成本；检查是否遗漏反例、边界场景、不熟悉但关键的部分。
+5. **评估与验证**：冲突来源列出各方观点→分析冲突原因→判断更可靠方；关键结论标注置信度（高/中/低/未知）。
+6. **综合分析**：方案全景 ≥3（保守/中间/激进）+ 成本全景 + 影响面 + 最坏情况（能否回滚、损失是否可控）。
+7. **元评审**（输出前自省）：剩余未知、最弱证据、可能错误的假设、遗漏角度、边际收益。
+8. **输出**：写 `docs/dev/research/<topic>.md`，并在消息中给结论/可执行建议摘要。
+
+## 调研纪律
+
+1. **先定义决策，后收集资料**：开始前写下"要回答什么问题"和"什么条件下选哪个方案"；结论不改变决策就不调研。
+2. **硬性约束优先于加权评分**：不满足硬性约束的方案直接淘汰，不进入评分表。
+3. **事实、推断、未知项分开**：不得把推断写成事实；无法验证就写"待验证"，禁止补全式猜测。
+4. **优先验证失败路径**，不只验证正常路径。
+5. **PoC 边界**：只验证会导致方案被否决的那个假设，不开发完整系统。
+6. **推荐必须包含适用边界、代价和退出条件**（什么信号出现时需要重新评估）。
+
+## 何时停止迭代
+
+- 所有关键问题 ≥2 个独立来源支持
+- 最重要的反方观点已覆盖
+- 剩余不确定性已标注，继续投入的边际收益递减
+
+## 输出
+
+- `docs/dev/research/<topic>.md`
+- 消息中的结论 / 可执行建议 / 待进一步盘问项
+
+## 获取仓库上下文（runnable）
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+gh issue view <issue-number>          # 若调研属于某 Flow/Task，读取其上下文
+gh api repos/"$REPO"/issues/<issue-number>/comments --jq '.[].body'
+```
+
+## Contract
+
+### Trigger
+由 `@dev-lifecycle` Phase 0 调研场景派发 `@researcher` 触发。
+
+### Inputs
+- 用户的调研问题 / 需求（含范围与输出形式）
+
+### Preconditions
+- 调研目标与范围明确；gh/git 可读（获取仓库与 Issue 上下文）
+- 需要外部资料时具备网络读取能力
+
+### Procedure
+1. 理解任务并制定研究计划
+2. 迭代收集并评分来源，追溯一手来源
+3. 反方搜索与遗漏检查
+4. 冲突处理与置信度标注
+5. 综合分析（方案/成本/影响面/最坏情况）
+6. 元评审后写 `docs/dev/research/<topic>.md` 并总结
+
+### Outputs
+- `docs/dev/research/<topic>.md`
+- 消息摘要
+
+### Failure
+- 无法访问可靠外部来源 → 说明并基于本地证据降级
+- 来源不足 → 明确标注「证据不足」，不编造
+
+### Idempotency
+- `docs/dev/research/<topic>.md` 已存在 → 更新而非新建重复文件
+
+### Prohibited Actions
+- 不编造来源、数据、案例或结论
+- 不改动代码（仅产出调研文档）
+- 不把未验证的二手/社区信息当作核心结论依据

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

@@ -0,0 +1,110 @@
+---
+name: flow-review
+description: 双轴审查（规范 + 规格）→ 发布审查结果 → 合并
+---
+
+# flow-review
+
+沿两条轴线审查 PR 代码：规范（是否符合编码标准）和规格（是否实现了原始需求）。
+reviewer 只读；写操作（review/merge）由 primary 编排器执行。
+
+## 核心流程
+
+1. **发布审查结果**（primary 执行）
+   ```bash
+   gh pr review <pr-number> --approve
+   gh pr review <pr-number> --request-changes --body "<原因>"
+   ```
+2. **合并**（CI + 审查通过后，primary 执行）
+   ```bash
+   HEAD_SHA=$(gh pr view <pr-number> --json headRefOid --jq .headRefOid)
+   gh pr merge <pr-number> --squash --delete-branch --match-head-commit "$HEAD_SHA"
+   ```
+3. 合并后清理 worktree：`git worktree remove ".worktree/<task-slug>"`（脏时提示用户手动处理）
+
+reviewer 只读：不直接执行 `gh pr review` / `gh pr merge`（写操作由 primary 编排器执行）。
+
+## 双轴审查
+
+两条轴线独立审查、分别报告；不把发现项混排，也不允许一条轴线的通过掩盖另一条轴线的失败。
+
+### 规格轴（Specification）
+
+回答“是否实现了正确的行为”：
+
+- 对照 PRD、Task `Builds`、`Acceptance Criteria` 与技术方案检查遗漏或不完整需求。
+- 检查 diff 是否增加规格未要求的行为或抽象，识别 scope creep。
+- 检查看似已实现但边界、错误或状态转换不符合规格的行为。
+- 逐条核查 Acceptance Criteria 是否由 Design `Testing Decisions` 约定的 Test Seam 上的行为测试或验证命令证明。
+- 测试存在不等于规格通过；实现与测试共同误解需求时仍应报告。
+
+### 规范轴（Convention / Code Quality）
+
+回答“实现是否写得正确”：
+
+- 检查仓库文档化规范、AGENTS.md 与相关 ADR；仓库规则优先。
+- 参考 `references/smell-baseline.md`，代码气味属于判断性问题，不冒充硬性规范。
+- 检查 KISS、YAGNI、SRP，以及是否存在浅 Module、透传层或只有一个假设 Adapter 的 Seam。
+- 检查测试是否描述行为、使用公共 Test Seam，并避免私有方法、内部调用次数/顺序、侧信道和循环论证。
+- 跳过 formatter、lint、typecheck 等工具已经强制执行且没有实际风险的机械问题。
+
+**明确不检查 commit order**：RED→GREEN 顺序是编码过程约束，reviewer 不审查 commit 历史。
+
+### 审查结论
+
+- 任一轴存在阻断问题 → `CHANGES_REQUESTED`。
+- 两轴都没有阻断问题 → `APPROVED`。
+- 报告必须分别给出每条轴线的发现数量和最高严重度，不跨轴线重新排序。
+
+## 审查材料获取
+
+代码审查必须在本地分支/worktree 中进行，禁止通过 WebFetch 或浏览器访问远程 PR 页面获取代码。
+
+## Output
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+## 后续
+- **/release** — 发布（如所有 PR 已合并）
+
+## Contract
+
+### Trigger
+由 `/review` 命令或 `@agent-dev-lifecycle` Phase 3 审查步骤触发。
+
+### Inputs
+- PR 编号、Task 文件与 Task Record（来源：`/code` 产出）
+- PRD 与技术方案（包含 Testing Decisions）
+
+### Preconditions
+- `/code` 已完成 → PR 已创建
+- Design 已包含本 Task 相关行为的 Testing Decisions；存量 Design 缺失时先返回 Design Gap，不提前给出审查结论
+
+### Procedure
+1. 在本地 worktree/分支获取 PR diff 与元数据
+2. 独立执行规格轴审查，核对行为、范围与 Acceptance Criteria 证据
+3. 独立执行规范轴审查，核对仓库规范、实现质量与测试质量
+4. 分轴输出结构化审查报告，不合并或重排发现
+5. primary 用 `gh pr review` 发布结果
+6. CI 通过后 primary 用 `gh pr merge` 合并并清理 worktree
+
+### Outputs
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+### Failure
+- Critical/High → request-changes
+- Testing Decisions 缺失或与仓库现实冲突 → 返回 Design Gap，由 primary 在当前 stage 完成 amendment 后重新审查
+- Worktree 清理失败 → 记录警告，不阻塞
+
+### Idempotency
+- 已合并的 PR → 跳过
+- 已审查的 PR → 更新结论
+
+### Prohibited Actions
+- **禁止使用 WebFetch 或任何 Web 工具获取远程 PR 代码** — 审查代码时必须本地读取源码文件
+- reviewer 不直接执行 `gh pr review` / `gh pr merge`（由 primary 编排器执行）
+- 不把规格轴与规范轴合并成单一问题列表或用一条轴线抵消另一条轴线
+- 不使用默认 --force 清理

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

@@ -0,0 +1,88 @@
+---
+name: flow-setup
+description: 初始化 — 探测环境 → 确认 Profile
+---
+
+# flow-setup
+
+初始化阶段：探测开发环境、确认 AGENTS.md Project Profile。
+纯 Prompt 流程：直接使用 git/gh 命令探测，Profile 由用户确认后写入根 AGENTS.md。
+
+## 核心流程
+
+1. **探测环境**
+   ```bash
+   gh auth status                        # gh CLI 认证
+   gh repo view --json nameWithOwner,defaultBranchRef  # 仓库与默认分支
+   ls .github/workflows/                 # 现有 CI/release workflow
+   ```
+
+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
+
+3. **写入根 AGENTS.md**：用户确认后，将 Profile 区块追加/替换到根 `AGENTS.md`：
+
+```markdown
+## Project Profile
+
+- test command: `npm test`
+- regression command: `npm test`
+- test file patterns: `test/**/*.test.ts`
+- implementation file patterns: `src/**/*.ts`
+- version bump rule: `breaking→major, feature→minor, fix→patch`
+- version file: `package.json`
+- tag format: `v{version}`
+- release workflow: `.github/workflows/release.yml`
+```
+
+## 存量项目接入（adopt）
+
+仓库已有文档时（`init` 只新增骨架、不改写已有文件；无 `.cabbage/` 时先经 flow-change 执行 `op:"init"`）：
+
+1. `cabbage({op:"adopt"})` 盘点 `docs/` 树之外的 Markdown → 生成 `.cabbage/` 下的 `adoption-report.md`；
+   每份文档得到四种动作：`keep`（已在编号目录）/ `migrate`（当前状态文档）/ `import`（历史记录）/
+   `review`（无法归类）。分类仅基于目录与文件名推断，**始终需要人工确认**。
+2. 逐行处理 `review`，与文档负责人确认归属；`import` 的历史记录（ADR/RFC/事故）原样归档，
+   **不改写内容**。
+3. `migrate` 用 `git mv` 保留历史，一个逻辑批次一个提交；移动后立即修正相对链接。
+4. 每批后 `cabbage({op:"validate"})` + 站点构建，确认无死链。
+5. 接入完成的判据：再次 `op:"adopt"` 应全部报告 `keep`。
+
+## Output
+- readiness 报告（git/gh 可用性、CI/release workflow 存在性）
+- 根 AGENTS.md `## Project Profile` 区块
+
+## Contract
+
+### Trigger
+由 `/setup` 命令触发。首次使用插件或切换新项目时执行。
+
+### Inputs
+- 用户对 readiness 报告 / Profile 覆盖项的确认
+
+### Preconditions
+- gh CLI 已认证（宿主 `gh auth`）
+
+### Procedure
+1. 用 gh/git 命令探测环境，输出 readiness 报告
+2. 缺失 CI/release workflow 时提示用户（可手工创建）
+3. 向用户逐项确认 Profile 配置
+4. 用户确认后写入根 AGENTS.md Profile 区块
+
+### Outputs
+- readiness 报告
+- 根 AGENTS.md Profile 区块
+
+### Failure
+- gh auth 失败 → 提示用户执行 `gh auth login` 后重试
+
+### Idempotency
+- Profile 已存在 → 覆盖为最新确认值
+
+### Prohibited Actions
+- 不写入未获用户确认的 Profile 项
+- 不假设测试命令为 npm（按用户确认的技术栈）

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

@@ -0,0 +1,220 @@
+---
+name: flow-tasks
+description: 将技术方案拆解为可独立实现的 tracer-bullet Task Plan 与 DAG
+---
+
+# flow-tasks
+
+将设计方案拆解为 Task Plan 与 DAG（有向无环图）。每个 Task 都是一条完整但狭窄的行为切片，可以交给一个 fresh-context developer agent 独立实现和验证。
+
+本 skill 只定义任务拆解与 Task Plan 产出。`@agent-architect` 不创建 GitHub Issue、不操作 GitHub lifecycle；调用方负责检查并发布 Task Plan。
+
+## Task 拆解规则
+
+每个 Task 必须：
+
+1. 交付一个可以观察或验证的新行为。
+2. 是垂直切片，而不是 Controller / Service / DAO 等技术分层。
+3. 可以交给一个 fresh-context developer agent 独立理解和实现。
+4. 完成以后仓库处于可工作的状态，而不是为下一个 Task 留空壳。
+5. `Blocked By` 只声明“前者未完成时，本 Task 无法开始”的真实阻塞关系。
+
+每个 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` 应说明“保持哪个现有行为不变，并消除哪个阻碍后续行为的具体结构问题”，不能写成文件或类的修改清单。
+
+## 反模式
+
+| 反模式 | 示例 | 正确做法 |
+|--------|------|----------|
+| 技术分层拆分 | `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
+
+- <blocking-task-slug>
+- 或 None
+
+## Implementation Notes
+
+<只记录真正限制实现方式的重要设计决策；不要复制具体实现步骤。>
+```
+
+`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。`@agent-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：`@agent-dev-lifecycle` 检查后自动发布。
+- 高风险 Flow：展示 Task Plan，用户确认后发布。
+- 用户主动 `/tasks`：展示 Task Plan，等待用户确认后发布。
+- `@agent-architect`：产出并返回 Task Plan 后停止，不执行发布。
+
+## Output
+
+- `docs/dev/tasks/*.md` — Agent Implementation Contracts
+- `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md` — Task DAG
+- 返回给调用方的 Task Plan 摘要与拓扑顺序
+
+## 后续
+
+- `@agent-dev-lifecycle` 检查并发布 GitHub Sub Issues
+- **/code** — 按 Task DAG 进入编码阶段
+
+## Contract
+
+### Trigger
+由 `/tasks` 命令或 `@agent-dev-lifecycle` Phase 2 委派 `@agent-architect` 触发。
+
+### Inputs
+- `docs/dev/specs/<title>.md` — 技术方案
+- 相关 PRD 与 ADR
+- Parent Issue 编号
+
+### Preconditions
+- `/design` 已完成，技术方案和 ADR 存在
+
+### Procedure
+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
+- Task 定义文件
+- Task DAG
+- 供调用方检查与发布的 Task Plan
+- 或结构化 Design Gap（存量 Design 缺少 Testing Decisions 时）
+
+### Failure
+- 无法从设计中确定可验证行为 → 暂停并指出缺失信息
+- Design Amendment 后仍缺少稳定 Test Seam → 报告未解决的 Design Gap，由调用方暂停当前阶段
+- DAG 存在环形依赖 → 阻止并报告
+- Task 无法由 fresh-context developer 独立理解 → 重新拆分或补足契约
+
+### Idempotency
+- Task 文件已存在 → 读取并更新，不创建重复定义
+- 已有 `issue` 编号 → 保留并交给调用方核验，不重复发布
+
+### Prohibited Actions
+- 不按技术层拆分 Task
+- 不为制造并行度而拆分 Task
+- 不创建完成后不可工作的空壳 Task
+- 不用 pre-refactor 包装搭框架、清理代码或预留扩展点
+- 不把非阻塞关系写入 `Blocked By`
+- `@agent-architect` 不执行 `gh issue create`、`git push`、PR、merge 或 worktree 操作