---
name: executing-plans
description: 当有书面实施计划需要在会话中执行时使用。加载计划，审阅后执行所有任务，完成后报告。当用户提及"执行计划"、"实施计划"、"运行计划"、"开始执行"或计划文档已准备好实施时触发。
license: MIT
metadata:
  version: "3.0.0"
---

# 执行计划技能

本技能用于执行书面实施计划，严格遵循文档步骤。

---

## 核心原则

### 执行优先

在计划完成前，请勿：

- 跳过审阅步骤
- 跳过验证步骤
- 在主分支上操作（除非获得明确批准）
- 猜测或假设

### 会话状态管理

使用统一的会话状态文件跟踪进度：

- **路径**：`design/session-state.md`
- **模板**：`references/session-state-template.md`（共享）

**操作时机**：

- 技能激活时 → **立即创建/更新状态文件**
- 完成任务后 → **立即更新状态文件**
- 每轮对话开始时 → 读取状态文件恢复上下文
- **每个 **阶段/任务** 完成后 → 立即更新状态文件**

### 终止条件

本技能的唯一终止方式是完成所有任务并生成完成报告。

---

## 任务状态

| 状态   | 说明                     |
| ------ | ------------------------ |
| 已完成 | 任务已完成，所有验证通过 |
| 进行中 | 任务正在执行中           |
| 待执行 | 任务尚未开始             |
| 阻塞   | 任务因问题被阻塞         |

---

## 工作流程

### 阶段 1：加载并审阅计划

**目标**：加载计划文档，进行批判性审阅。

**执行动作**：

1. 运行 `git branch --show-current` 确认当前分支
2. 如果在 main/master 分支，停止并询问是否继续
3. 读取计划文档
4. 批判性审阅计划
5. **验证测试覆盖**

**审阅检查清单**：

- [ ] 目标是否清晰且可实现？
- [ ] 所有文件路径是否精确且正确？
- [ ] 代码片段是否完整（非占位符）？
- [ ] 测试命令对项目是否准确？
- [ ] 每个步骤是否足够细粒度（2-5分钟）？
- [ ] 每个任务是否都包含测试步骤？
- [ ] 测试文件路径是否明确且完整？
- [ ] 测试用例是否覆盖主要功能？

**测试覆盖验证**：

⚠️ **强制检查项**：

- 检查每个任务是否定义了测试文件路径
- 验证测试文件路径不为空、不是占位符
- 确认测试用例覆盖了核心功能
- 如果发现测试缺失，立即停止并要求补充测试计划

**决策点**：

- 若发现疑虑 → 记录问题，与用户讨论后再继续
- 若测试覆盖不足 → 要求返回 writing-plan 补充测试
- 若无疑虑 → 创建任务列表，进入阶段 2

**完成标准**：计划已审阅，测试覆盖已验证，任务列表已创建

---

### 阶段 2：执行任务

**目标**：按计划执行每个任务。

**执行规则**：

对于计划中的每个任务：

1. 在任务列表中将任务标记为"进行中"
2. **验证测试文件存在**（如果不存在，先创建测试文件）
3. 完全按照书面执行每个步骤
4. 按照 TDD 流程执行测试，测试必须通过，测试失败必须修复
5. 运行指定的验证
6. **检查是否需要添加代码注释**
7. 在任务列表中将任务标记为"已完成"
8. 更新会话状态文件
9. 如果计划指定，则提交

**添加代码注释调用格式**：

```
调用 code-commentator 技能，目标文件：[文件路径]
```

**步骤执行规则**：

- 修改前先读取现有文件
- 使用计划中的确切代码
- 按计划中指定的方式执行命令
- 检查实际输出是否与预期输出匹配

**验证要求**：

每个任务在进入下一个之前必须通过其验证：

- 测试必须通过（不仅仅是运行）
- 构建必须成功
- Lint 必须通过
- 代码注释已添加（如需要）

**错误处理**：

错误发生时：

1. 记录错误到会话状态文件
2. 停止并寻求帮助

**完成标准**：所有任务已执行，所有测试已通过，代码注释已添加，验证已通过

---

### 阶段 3：完成与报告

**目标**：生成完成报告，更新项目上下文。

**执行动作**：

1. 运行最终验证套件
2. 更新会话状态文件标记完成
3. 生成完成报告
4. **使用 project-context 技能更新项目上下文**
5. **使用 project-context 技能更新用户画像**（如果识别到新的偏好）

**完成报告格式**：

```markdown
## 实施完成

**计划**：[计划文件路径]
**状态**：✅ 所有任务已完成

### 摘要

[已构建内容的简要描述]

### 变更文件

- 新建：[新文件列表]
- 修改：[修改文件列表]

### 验证结果

- 测试：✅ 通过
- 构建：✅ 成功
- Lint：✅ 干净
```

**完成标准**：报告已生成，项目上下文已更新，用户画像已更新（如有变化）

---

## 何时停止并寻求帮助

**在以下情况下立即停止执行**：

| 情况             | 行动                   |
| ---------------- | ---------------------- |
| 缺少依赖项       | 请求用户安装或提供     |
| 测试反复失败     | 调试并在卡住时寻求指导 |
| 指令不明确       | 请求澄清，不要猜测     |
| 计划存在关键缺陷 | 返回阶段一进行计划修订 |
| 出现意外错误     | 记录错误并寻求帮助     |

**停止协议**：

1. 记录阻碍到会话状态文件
2. 解释尝试了什么
3. 提出具体问题
4. 等待指导

---

## 多子系统处理

当计划包含多个子系统时：

1. 读取纲领文件，识别子系统数量
2. 验证依赖关系，按执行顺序排列
3. 按依赖顺序执行每个子系统（阶段一 → 阶段二 → 阶段三）
4. 共享组件在第一个使用它的子系统中实现

---

## 被其他技能调用

当被 writing-plan 技能调用时：

**接收参数**：

- `plan_path`：计划文档路径（必需）
- `subsystem_paths`：子系统计划路径列表（多子系统时必需）
- `outline_path`：纲领文件路径（如适用）

**跳过触发条件检查**，直接创建会话状态文件并进入阶段一。

---

## 参考指南

| 参考文档                                   | 用途             |
| ------------------------------------------ | ---------------- |
| `references/execution-state-template.md`   | 执行状态记录模板 |
| `references/completion-report-template.md` | 完成报告模板     |

---

## 常见问题

### 对话中断后如何恢复？

处理方式：

1. 读取会话状态文件 `design/session-state.md`
2. 验证已完成任务的代码和测试
3. 向用户报告恢复选项

### 计划需要修改？

处理方式：

1. 返回阶段一进行计划审阅
2. 与用户讨论修改方案
3. 修改后重新执行

### 遇到阻碍？

处理方式：

1. 记录问题到会话状态文件
2. 停止并询问用户
3. 不要强行突破阻碍