---
name: planning-apply-change
description: 执行变更实现。融合 OpenSpec apply + Superpowers SDD 引擎。这是最关键的融合点 — 用 SDD 子代理驱动方式执行 OpenSpec 定义的任务。
---

# 应用变更 (Apply Change)

使用 SDD (子代理驱动开发) 引擎执行 OpenSpec 变更中的任务。

**这是 SpecPow 的核心融合点：**
- OpenSpec 提供任务定义和规范约束
- Superpowers SDD 提供高质量的执行引擎

## 输入

可选指定变更名称（如 `/apply-change add-auth`）。如果省略，从对话上下文推断或提示选择。

## 流程

### 1. 选择变更

如果提供了名称，使用它。否则：
- 从对话上下文推断
- 如果只有一个活跃变更，自动选择
- 如果有歧义，运行 `specpow list --json` 让用户选择

总是宣布："使用变更: <name>"

### 2. 检查状态并理解 Schema

```bash
specpow status --change <name> --json
```

理解：
- `schemaName`: 使用的工作流
- `changeRoot`: 变更目录
- 哪个工件包含任务（通常是 "tasks"）

### 3. 获取应用指令

```bash
specpow instructions apply --change <name> --json
```

返回：
- `contextFiles`: 工件 ID 或文件路径数组
- 进度（总数、完成、剩余）
- 任务列表及状态
- `context`: 项目约束（必须考虑但不复制到文件）

### 4. 读取上下文文件
读取 `contextFiles` 中列出的所有文件：
- proposal.md — 理解为什么做
- specs/ — 理解行为契约（审查时会验证）
- design.md — 理解技术方案
- tasks.md — 理解要做什么

### 5. 初始化 SDD 引擎

```
使用 SDD 引擎执行计划。
[设置: 工作区已验证]
[读取计划文件: tasks.md]
[创建工作区 .specpow/changes/<plan-name>/sdd/]
[初始化账本]
[为所有任务创建 todo]
```

### 6. 执行任务循环（SDD 驱动）
对每个待处理任务：

#### a. 提取任务简报
```bash
# 提取任务的完整文本到独立文件
scripts/task-brief tasks.md <N>
```

#### b. 分发实现者子代理

构建分发 prompt，包含：
1. 一行项目背景
2. 简报路径（"先读这个 — 它是你的需求"）
3. 来自前置任务的接口信息
4. OpenSpec 规范约束（从 specs/ 中提取）
5. 报告文件路径

**关键：不粘贴历史任务的累积摘要。每个子代理只需要自己的任务简报。**

#### c. 实现者执行
实现者子代理：
1. 读取简报
2. 实现代码
3. 编写测试（TDD）
4. 提交
5. 自审
6. 写入报告文件

#### d. 生成审查包并分发审查者
```bash
# 生成审查包（diff 文件）
scripts/review-package PLAN_FILE BASE HEAD
```

分发任务审查子代理，提供：
- 简报路径
- 报告路径
- 审查包路径
- OpenSpec 规范约束（用于验证合规性）

#### e. 处理审查结果

- **通过**: 记录到账本，继续下一任务
- **不通过**: 进入修复循环

#### f. 修复循环（最多 5 轮）

- **Rounds 1-3**: 恢复原始实现者
- **Rounds 4-5**: 分发全新实现者，使用更强模型

每轮：
1. 实现者修复
2. 重新运行测试
3. 范围限定的重新审查
4. 记录到账本

#### g. 断路器（5 轮后）
如果仍有开放发现：
- 审查者误报 → 停放（代码保留）
- 真实但无下游依赖 → 停放（延迟修复）
- 真实且承载依赖 → STOP，报告 BLOCKED

### 7. 最终审查
所有任务完成后：
```bash
scripts/review-package PLAN_FILE MERGE_BASE HEAD
```

分发最终审查（使用最强模型），审查整个分支。

### 8. 完成

- 更新 tasks.md 中的任务状态（YAML 格式：`status: done`；Checkbox 格式：`- [x]`）
- 删除 SDD 工作区
- 提示使用 `finish-branch` 技能

## 输出格式

```
## 实现 <change-name> (schema: <schema-name>)

正在处理任务 3/7: <任务描述>
[...实现中...]
✓ 任务完成

正在处理任务 4/7: <任务描述>
[...实现中...]
✓ 任务完成
```

## 护栏

- 持续推进直到完成或被阻塞
- 开始前总是读取上下文文件
- 任务不明确时暂停询问
- 实现发现问题时暂停建议更新工件
- 保持代码变更最小化和聚焦
- 完成后立即更新任务勾选状态
- 遇到错误或阻塞时暂停 — 不要猜测

## 关键融合点

**OpenSpec 规范约束注入到 SDD 子代理：**

实现者的 prompt 中包含：
```
规范约束（来自 specs/<capability>/spec.md）：
- REQ-001: 系统必须 <行为>
- REQ-002: 系统必须 <行为>

审查时将验证这些约束是否被满足。
```

这确保实现不仅代码正确，还符合规范定义的行为契约。

## 合理化防御表

| 借口 | 现实 |
|------|------|
| "我可以直接在主会话中实现" | 主会话上下文会被污染。用子代理。 |
| "审查太慢了" | 没有审查的循环只是未验证的折腾。 |
| "账本记录是多余的" | 账本是压缩后存活的东西。没有它你会重复已完成的任务。 |
| "修复很小，跳过重新审查" | 未审查的修复是回归的方式。每轮都以重新审查结束。 |
| "规范约束不重要" | 规范是行为契约。审查会验证。 |