---
name: execution-subagent-dispatch
description: 子代理派发技能。将 ai-caller.ts 的三种 prompt 模板（实现者、审查者、重审者）转化为宿主 Agent 可执行的指令。当需要派发子代理执行具体任务时使用。
version: 1.0.0
trigger: on-demand
---

# 子代理派发技能

当需要派发子代理执行实现、审查或重审任务时，按以下模板构建指令。

## 核心原则

1. **文件即接口** — 告诉子代理去哪里读文件，不在 prompt 中粘贴大段内容
2. **新鲜上下文** — 每个子代理只获得它需要的文件路径，不继承历史对话
3. **输出到文件** — 所有结果写入指定文件，不通过对话返回

---

## 实现者子代理 Prompt 模板

派发实现者时，给子代理的指令应包含以下部分：

```markdown
# 任务实现

## 上下文
你正在项目 {projectContext} 中工作。

## 任务简报
请阅读完整的任务简报文件: {briefPath}

## 规范约束
{specConstraints}
（如无 spec，写"遵循项目现有代码风格和架构约定"）

## 涉及文件
{filesList}
（如无指定文件，写"由你自行判断需要修改的文件"）

## 铁律：测试驱动开发 (TDD)

没有失败测试就不写产品代码！

## 执行步骤 — RED-GREEN-REFACTOR

### RED — 先写一个失败的测试
1. 阅读任务简报，理解需求行为
2. 为下一个要实现的 _行为_ 写一个测试
3. 运行测试，确认它失败
4. 失败原因必须是"功能还不存在"

### GREEN — 写最少的代码让测试通过
1. 写刚好够让测试通过的代码
2. 不多写。YAGNI。
3. 运行测试，确认全部通过

### REFACTOR — 在测试保护下清理代码
1. 消除重复，改善命名
2. 运行测试，确认仍然全部通过

重复 RED-GREEN-REFACTOR 直到任务完成。

## 报告要求
将详细的实现报告写入: {reportPath}

报告格式（文本要点）：
```
报告格式：
- 状态: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
- 产生的 commit 列表（如果适用）
- 测试摘要（RED 阶段写了哪些测试，GREEN 阶段全部通过）
- 任何疑虑或未解决的问题
```

注意：`parseTaskReport` 同时接受上述文本格式和 JSON 格式。JSON 格式使用大写状态值：`"status": "DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED"`。
```

### 变量说明

| 变量 | 来源 | 示例 |
|------|------|------|
| `{projectContext}` | 项目根目录名 | `specpow` |
| `{briefPath}` | 任务简报路径 | `.specpow/changes/{change}/sdd/task-{N}-brief.md` |
| `{specConstraints}` | specs/ 目录中的规范内容 | 从 `specs/*.md` 读取 |
| `{filesList}` | 任务涉及的文件列表 | 从任务描述中提取 |
| `{reportPath}` | 实现报告输出路径 | `.specpow/changes/{change}/sdd/task-{N}-report.md` |

### Fix 轮次的实现者派发

修复轮次复用相同的 prompt 模板，但：
- **不修改 brief 文件** — 复用原始 brief，open findings 通过指令传递
- **追加 open findings 列表** — 在 prompt 中列出需要修复的 findings
- **reportPath 变更** — 写入 `task-{N}-report.md.fix-{R}`（不是覆盖原 report）
- **模型升级** — 第 4-5 轮使用比当前高一级模型

---

## 审查者子代理 Prompt 模板

派发审查者时，给子代理的指令应包含以下部分：

```markdown
# 代码审查 — 三阶段裁决

## 任务上下文
- 任务: {taskTitle}
- 简报: {briefPath}

## 审查包
请阅读完整的审查包: {reviewPackagePath}

## 审查流程

### 第一阶段: 规格合规裁决
对照任务简报，逐项检查：
1. 所有需求项是否已实现
2. 是否有超出规范的实现（scope creep）
3. 接口签名是否与设计一致

### 第二阶段: 代码质量裁决
1. 命名和结构是否清晰
2. 错误处理是否完整
3. 是否有安全隐患
4. 是否有性能问题

### 第三阶段: TDD 合规裁决
1. 是否有测试覆盖新增/修改的代码
2. 测试是否断言行为而非实现细节
3. 测试是否在代码之前编写（检查 commit 顺序或测试结构）
4. 关键路径和边界条件是否有测试

## 输出格式
将审查结果写入文件: {reviewResultPath}

```json
{
  "specCompliant": true/false,
  "qualityApproved": true/false,
  "findings": [
    {
      "id": "F-001",
      "severity": "critical|important|minor",
      "description": "...",
      "file": "path/to/file",
      "line": 42,
      "isLoadBearing": true/false
    }
  ],
  "cannotVerify": ["从 diff 无法验证的项目"]
}
```
```

### 变量说明

| 变量 | 来源 | 示例 |
|------|------|------|
| `{taskTitle}` | 任务标题 | 从 brief 中读取 |
| `{briefPath}` | 任务简报路径 | `.specpow/changes/{change}/sdd/task-{N}-brief.md` |
| `{reviewPackagePath}` | 审查包路径（diff） | `.specpow/changes/{change}/sdd/review-package.md` |
| `{reviewResultPath}` | 审查结果输出路径 | `.specpow/changes/{change}/sdd/review-result.json` |

### 审查要点

- **不输出 `addressed` 字段** — 初始审查不判断 addressed，该字段由重审者填充
- **cannotVerify** — 无法从 diff 验证的项目（如运行时行为、外部依赖）放在此数组中
- **isLoadBearing** — 标记该 finding 是否为承重墙（阻塞性），非承重墙的 finding 可以 park

---

## 重审者子代理 Prompt 模板

派发重审者时（修复循环中），给子代理的指令应包含以下部分：

```markdown
# 范围限定重新审查

只审查修复 diff: {fixDiffPath}

## 待验证的开放发现
{openFindingsList}

## 要求
对每个发现做出裁决: ADDRESSED / NOT ADDRESSED
新问题（仅限修复 diff 内的）标记为 NEW
超出修复范围的观察 → 忽略（不记录）

将结果写入: {reReviewResultPath}
```

### 变量说明

| 变量 | 来源 | 示例 |
|------|------|------|
| `{fixDiffPath}` | 修复 diff 路径 | `.specpow/changes/{change}/sdd/review-package.md`（复用审查包命名） |
| `{openFindingsList}` | 开放 findings 列表 | 格式化后的 finding 列表（见下方） |
| `{reReviewResultPath}` | 重审结果输出路径 | `.specpow/changes/{change}/sdd/re-review-result.json` |

### Open Findings 列表格式

```
  1. [critical] Description of finding 1 (src/foo.ts:42)
  2. [important] Description of finding 2 (src/bar.ts)
  3. [minor] Description of finding 3
```

### 重审要点

- **只审查修复部分** — 不重新审查整个任务，只看 fix diff
- **对每个 finding 裁决** — ADDRESSED 或 NOT ADDRESSED
- **新问题限制范围** — 只有在 fix diff 内发现的新问题才标记为 NEW
- **超出范围忽略** — 不在 fix 范围内的观察不记录

---

## 派发流程（宿主 Agent 操作）

### 1. 实现者派发

```bash
# 1. 确保 brief 文件已写入
# （由编排技能在步骤 2a 完成）

# 2. 使用宿主原生 subagent 工具派发
# Claude Code: Agent tool
# Cursor: subagent tool
# 其他: 参考宿主工具文档

# 3. 子代理读取 brief → 实现 → 写 report

# 4. 读取 report 文件，解析 JSON
```

### 2. 审查者派发

```bash
# 1. 生成审查包（diff）
BASE_COMMIT={recorded base commit}
HEAD_COMMIT=$(git rev-parse HEAD)
git diff ${BASE_COMMIT}..${HEAD_COMMIT} > .specpow/changes/{change}/sdd/review-package.md

# 2. 使用宿主原生 subagent 工具派发审查者
# Prompt: 审查者模板（见上方）

# 3. 子代理读取 brief + review package → 审查 → 写 review-result.json

# 4. 读取 review-result.json，解析 JSON
```

### 3. 重审者派发（修复循环中）

```bash
# 1. 生成修复 diff（复用 generateReviewPackage 命名模式）
FIX_BASE=$(git rev-parse HEAD)
# 实现者修复后...
FIX_HEAD=$(git rev-parse HEAD)
git diff ${FIX_BASE}..${FIX_HEAD} > .specpow/changes/{change}/sdd/review-package.md

# 2. 使用宿主原生 subagent 工具派发重审者
# Prompt: 重审者模板（见上方）+ open findings 列表

# 3. 子代理读取 fix diff → 对每个 finding 裁决 → 写 re-review-result.json

# 4. 读取 re-review-result.json，解析 JSON
```

---

## 模型选择指导

根据任务复杂度选择子代理模型（如果宿主工具支持）：

| 场景 | 条件 | 推荐级别 |
|------|------|----------|
| 机械实现 | ≤2 文件 + 完整 spec | cheap（默认 haiku） |
| 集成实现 | 多文件协调 | standard（默认 sonnet） |
| 架构设计 | 需要设计判断 | capable（默认 opus） |
| 简单审查 | <100 行 diff | cheap（默认 haiku） |
| 标准审查 | 一般变更 | standard（默认 sonnet） |
| 复杂审查 | 复杂变更 | capable（默认 opus） |
| 最终审查 | 全变更审查 | capable（默认 opus） |
| 修复轮次 4-5 | 升级模型 | 比当前高一级 |

**注意**：这只是指导。根据你实际可用的模型做出最佳选择。

---

## 关键原则

1. **文件即接口** — 所有产物通过文件传递，不占用上下文
2. **范围限定** — 重审者只审查修复部分，提高效率
3. **铁律 TDD** — 实现者必须遵循 RED-GREEN-REFACTOR
4. **三阶段审查** — 规格合规 → 代码质量 → TDD 合规
5. **模型升级** — 修复轮次 4-5 升级模型，避免卡死