Skill: cloudyli/iterate-planning (version 1.0.0)

--- name: iterate-planning description: | 基于 Ralph Loops 三阶段工作流理念，适配 OpenClaw 架构。 需求迭代工作流：需求讨论 → 计划拆解 → 迭代执行。 触发条件：用户说"讨论需求"、"开始计划"、"迭代执行"、"需求访谈" --- # 需求迭代工作流 (Iterate Planning) 基于 Ralph Loops 三阶段工作流，适配 OpenClaw 原生实现。 ## 核心哲学 > Human roles shift from "telling the agent what to do" to "engineering conditions where good outcomes emerge naturally through iteration." 三个原则： - **Context is scarce** — 保持每次迭代精简 - **Plans are disposable** — 漂移的计划重新生成比修复更划算 - **Backpressure beats direction** — 工程化环境让错误的输出自动被拒绝 ## 三阶段工作流 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Phase 1: 需求访谈 │ │ 结构化对话 → 识别JTBD → 拆分Topics → 产出 specs/*.md │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 2: 计划 │ │ Gap分析(specs vs code) → 产出 IMPLEMENTATION_PLAN.md │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 3: 迭代执行 │ │ 每次一个任务 → 全新上下文 → 验证 → 提交 → 下一任务 │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## Phase 1: 需求访谈 **目标**：在动手写代码之前，真正理解要做什么。 **触发**：用户说"讨论需求"、"需求访谈"、"帮我理清需求" **流程**： 1. 使用 `templates/requirements-interview.md` 模板进行结构化访谈 2. 识别 JTBD（Jobs to Be Done）— 用户真正要解决的Outcome，不是功能列表 3. 把 JTBD 拆分成 Topics of Concern（每个 topic 一个独立维度） 4. 用"一个句子，不带and"测试 — 能说出来的是一个topic，说不出来的是多个 5. 每个 Topic 写一份 `specs/topic-xxx.md` **完成标志**： - 每个 Topic 都有 `specs/*.md` - 每个 spec 包含：需求描述、验收标准、边界情况 **交付物**： ``` project/ └── specs/ ├── topic-a.md ├── topic-b.md └── ... ``` --- ## Phase 2: 计划 **目标**：生成可执行的任务清单，不写代码。 **触发**：需求完备后，用户说"开始计划"、"可以拆任务了" **流程**： 1. 读取 `specs/*.md` 所有需求 2. 如有现有代码，研究 codebase 3. 对比 specs vs code（Gap Analysis） 4. 生成 `IMPLEMENTATION_PLAN.md`（带优先级的任务列表） **模板**：`templates/planning-prompt.md` **完成标志**： - `IMPLEMENTATION_PLAN.md` 存在 - 每个任务有优先级标注 - 任务列表完整覆盖所有 specs **交付物**： ``` project/ ├── specs/ ├── IMPLEMENTATION_PLAN.md └── ... ``` --- ## Phase 3: 迭代执行 **目标**：每次做一个任务，全新上下文，保持 agent 在"聪明区域"。 **触发**：计划完备后，用户说"开始执行"、"迭代构建" **核心洞察**： - **一次一任务** — 保持上下文精简，agent 保持高效 - **全新上下文** — 每次迭代从头开始，之前的错误不累积 - **验证 + 提交** — 每个任务完成后必须验证才能提交 **流程**： 1. 读取 `IMPLEMENTATION_PLAN.md` 2. 选最高优先级任务 3. 研究 codebase（不要假设未实现） 4. 执行任务 5. 运行验证（backpressure） 6. 更新 plan（标记完成） 7. 提交 commit 8. 循环直到 plan 完成 **模板**：`templates/build-prompt.md` **完成标志**： - `IMPLEMENTATION_PLAN.md` 所有任务标记 done - 每次迭代有对应 commit --- ## 触发词指南 | 用户说 | Agent 动作 | |--------|-----------| | "讨论需求"、"需求访谈" | 启动 Phase 1 需求访谈 | | "开始计划"、"可以拆任务了" | 启动 Phase 2 计划生成 | | "开始执行"、"迭代构建" | 启动 Phase 3 迭代执行 | | "Ralph Loop"、"迭代" | 询问用户要哪个 phase | --- ## 文件结构 ``` iterate-planning/ ├── SKILL.md # 本文件 ├── AGENTS.md # 操作员指南 └── templates/ ├── requirements-interview.md # 需求访谈模板 ├── planning-prompt.md # 计划生成提示词 └── build-prompt.md # 构建执行提示词 ``` --- ## 为什么有效 | 问题 | 解法 | |------|------| | 需求不清晰就动手 | Phase 1 强制结构化访谈 | | 计划赶不上变化 | Plans are disposable — 重新生成比修复更划算 | | 上下文膨胀导致幻觉 | 一次一任务，全新上下文 | | 错误累积难以追溯 | 每次验证 + 提交，自然 checkpoint |

path: AGENTS.md
content: # AGENTS.md — 需求迭代工作流操作员指南

## 概述

这是一个人机协作的需求迭代工作流。人的角色从"告诉 agent 做什么"转变为"工程化条件，让好的结果通过迭代自然出现"。

## 三阶段

| 阶段 | 触发 | 产出物 |
|------|------|--------|
| Phase 1: 需求访谈 | "讨论需求"、"需求访谈" | specs/*.md |
| Phase 2: 计划 | "开始计划"、"可以拆任务了" | IMPLEMENTATION_PLAN.md |
| Phase 3: 迭代执行 | "开始执行"、"迭代构建" | 代码 + git commits |

---

## Phase 1: 需求访谈

### 何时触发
用户说"讨论需求"、"需求访谈"、"帮我理清需求"

### 操作步骤
1. **开场**：告诉用户你会通过结构化提问来理清需求
2. **追问**：用 requirements-interview.md 模板提问
3. **记录**：把讨论结果写入 specs/topic-xxx.md
4. **确认**：每个 topic 完成后确认用户认可
5. **收尾**：全部 topic 完备后，让用户确认整体

### 关键原则
- 问 Outcome，不问功能
- 用"一个句子，不带and"拆分 Topic
- 每个 spec 的验收标准必须可测试

### 验收清单
- [ ] 每个 Topic 有 specs/*.md
- [ ] 每个 spec 有明确的验收标准
- [ ] 边界情况已识别
- [ ] 用户已确认

---

## Phase 2: 计划

### 何时触发
用户说"开始计划"、"可以拆任务了"

### 操作步骤
1. 读取所有 specs/*.md
2. 如有现有代码，研究 codebase
3. 使用 planning-prompt.md 生成任务列表
4. 产出 IMPLEMENTATION_PLAN.md
5. 向用户确认计划

### 关键原则
- 只做计划，不写代码
- 任务要小到一次迭代可完成
- 按依赖关系排序

### 验收清单
- [ ] 所有 specs 都有对应任务
- [ ] 任务按优先级排列
- [ ] 用户已确认计划

---

## Phase 3: 迭代执行

### 何时触发
用户说"开始执行"、"迭代构建"

### 操作步骤
1. 读取 IMPLEMENTATION_PLAN.md
2. 选最高优先级未完成任务
3. 使用 build-prompt.md 执行
4. 验证 → 提交 → 更新 plan
5. 循环直到完成或用户停止

### 关键原则
- 一次一任务，不要扩散
- 每次迭代后立即验证和提交
- 遇到阻塞记录原因，继续下一任务

### 验证清单（每轮迭代）
- [ ] 任务完成，验收标准满足
- [ ] git commit 已创建
- [ ] IMPLEMENTATION_PLAN.md 已更新
- [ ] 用户知道当前进度

### 报告模板（每次迭代后）
```
✅ 已完成：[任务标题]
📝 Commit: [commit hash]
📋 进度：X/Y 任务完成

🔜 下一个：[任务标题]
```

---

## 沟通原则

### 不要阻塞对话
Ralph Loop 运行时不同步监控。让用户知道：
- "Loop 正在运行，我会周期性检查进度"
- "你可以随时问我进度"
- 不要 sleep 等待

### 遇到问题
1. 记录到 plan 注释
2. 标记 blocked
3. 报告用户："任务X因[原因]阻塞，我跳过继续做任务Y"

### 用户可以随时
- 问进度
- 修改计划
- 停止迭代
- 增加/删除任务

---

## 文件结构

```
[项目目录]/
├── specs/
│   ├── topic-a.md
│   └── topic-b.md
├── IMPLEMENTATION_PLAN.md
└── （项目代码）

skills/iterate-planning/
├── SKILL.md
├── AGENTS.md
└── templates/
    ├── requirements-interview.md
    ├── planning-prompt.md
    └── build-prompt.md
```


path: templates/build-prompt.md
content: # 构建执行提示词 (Build Prompt)

## 用途
Phase 3 使用。每次迭代执行一个任务时使用。

## 核心原则

**一次一任务，全新上下文**

每个任务迭代：
1. 读取 IMPLEMENTATION_PLAN.md
2. 选最高优先级未完成任务
3. 全新上下文执行
4. 验证
5. 提交
6. 更新 plan

## 提示词内容

```
你是执行阶段 agent。你的任务是根据计划完成一个具体任务。

## 当前上下文
- 项目路径：[PROJECT_PATH]
- 当前任务：[TASK_TITLE]
- 对应 Spec：[SPEC_FILE.md]

## 任务描述
[TASK_DESCRIPTION]

## 验收标准
- [ ] [可测试的标准1]
- [ ] [可测试的标准2]

## 你的任务

### Step 1: 研究
- 读取对应 spec
- 研究现有代码（不要假设没实现）
- 确认需要做什么改动

### Step 2: 实现
- 做最小改动完成任务
- 遵循现有代码风格
- 不要引入技术债

### Step 3: 验证
运行验证确保正确：
- 语法正确
- 对应 spec 的验收标准已满足
- 现有测试通过（如有）

### Step 4: 提交
- `git add .`
- `git commit -m "[TASK_TITLE]: 完成 [简短描述]"`
- message 格式：`{type}: {description}`（type: feat/fix/refactor/docs/test）

## 注意事项
- 只做一个任务，不要扩散
- 每次 commit 要清晰可 revert
- 如果遇到阻塞，记录到 plan 注释里
- 完成后更新 IMPLEMENTATION_PLAN.md（标记 done）

## 验证命令（参考）
根据项目类型选择：
- Node.js: `npm run build && npm test`
- Python: `python -m pytest`
- Go: `go build ./... && go test ./...`
- 通用: `make test` 或项目对应的验证命令

---

## 迭代循环

```
[选任务] → [研究] → [实现] → [验证] → [提交] → [更新plan] → [下一任务]
     ↑                                                                    |
     └──────────────────── (循环直到 plan 完成) ←────────────────────────┘
```

## 迭代检查清单

每次迭代结束确认：
- [ ] 任务完成，验收标准满足
- [ ] git commit 已创建
- [ ] IMPLEMENTATION_PLAN.md 已更新（任务标记 done）
- [ ] 如有阻塞，记录原因

## 何时停止
- 所有 P0 任务完成
- 所有 P1 任务完成
- 用户主动停止

## 遇到问题怎么办
1. 记录问题到 plan 注释
2. 标记任务为 blocked
3. 继续下一任务
4. 向用户报告阻塞情况
```


path: templates/planning-prompt.md
content: # 计划生成提示词 (Planning Prompt)

## 用途
Phase 2 使用。当需求完备后，用这份提示词生成 IMPLEMENTATION_PLAN.md。

## 前提条件
- `specs/*.md` 已存在且完备
- （如有）现有代码库已研究

## 提示词内容

```
你是计划阶段 agent。你的任务是基于需求 spec 生成可执行的任务计划。

## 输入
- 需求文档：`specs/*.md`（所有 topic 的完整需求）
- （如有）现有代码库结构

## 你的任务

### Step 1: 研究需求
- 读取所有 `specs/*.md`
- 理解每个 topic 的验收标准

### Step 2: Gap 分析
对比需求 vs 现有代码（如果有）：
- 哪些功能已经实现？
- 哪些功能部分实现需要修改？
- 哪些功能完全没实现？

### Step 3: 生成任务列表
为每个"未实现"或"需修改"的功能点，拆分具体任务。

任务格式：
```
## [任务标题]

**对应 Spec**: [哪个 spec/topic]
**优先级**: P0/P1/P2
**描述**: [一句话描述要做什么]
**验收标准**: 
- [ ] [可测试的具体标准]
**估计复杂度**: [低/中/高]
**依赖**: [其他任务或外部依赖]
```

### Step 4: 排序
按以下原则排序：
1. P0 > P1 > P2
2. 同优先级内：依赖少的先做
3. 核心功能先做，边缘功能后做

## 输出格式

生成 `IMPLEMENTATION_PLAN.md`：

```markdown
# Implementation Plan

## 项目概述
[一句话描述项目目标]

## 已完成的功能
- [ ] [已实现的功能列表]

## 待实现任务

### P0（必须）
...（任务列表）

### P1（重要）
...（任务列表）

### P2（可选）
...（任务列表）

## 执行顺序
1. [任务标题]
2. [任务标题]
...

## 风险点
- [潜在风险] → 缓解方案
```

## 注意事项
- 只做计划，不写代码
- 任务要足够小：一个任务 = 一次迭代可以完成
- 验收标准必须可测试
- 不要假设实现方式，只描述"做什么"
```

---

## 使用方法

1. 把上述提示词作为 system prompt 或 user message
2. 确保 specs/*.md 已准备好
3. 让 agent 生成 IMPLEMENTATION_PLAN.md
4. 用户确认后进入 Phase 3

## 完成标志
- `IMPLEMENTATION_PLAN.md` 存在
- 所有 specs 都有对应任务
- 任务按优先级排列
- 用户已确认计划


path: templates/requirements-interview.md
content: # 需求访谈模板 (Requirements Interview)

## 目标
在动手之前，真正理解用户要解决什么问题、达成什么 Outcome。

## 原则

**问 Outcome，不要问功能。**

| ❌ 不要问 | ✅ 要问 |
|-----------|--------|
| "需要哪些功能？" | "解决了这个问题之后，你的生活/工作会有什么不同？" |
| "用户能做什么？" | "用户真正想完成什么？为什么这件事重要？" |
| "有什么技术要求？" | "怎么才算成功？有哪些衡量标准？" |

## 访谈流程

### Step 1: 识别 JTBD（Jobs to Be Done）

**核心问题**：
1. "你想解决什么问题？"
2. "为什么这个问题重要？"
3. "解决之后会带来什么不同？"

**记录格式**：
```
JTBD: [一句话描述用户真正想要完成的Outcome]
来源: [用户原话或背景]
重要性: [P0/P1/P2]
```

### Step 2: 拆分 Topics of Concern

**每个 Topic = 一个独立的关注维度**

用"一个句子，不带and"测试：
- ✅ "颜色提取系统分析图片识别主色调"
- ❌ "用户系统处理认证、 profiles、和计费" → 这是3个Topics

**Topic 命名**：[what it does]-[who benefits]

### Step 3: 每个 Topic 写 Spec

创建 `specs/topic-[name].md`：

```markdown
# [Topic 名称]

## 需求描述
[一句话描述这个 Topic 要做什么]

## 用户视角
[从用户角度描述：用户看到这个功能会怎样]

## 验收标准 (Acceptance Criteria)
- [ ] [标准1：可测试、可观察]
- [ ] [标准2]
- [ ] [标准3]

## 边界情况 (Edge Cases)
- [情况1]：期望行为是...
- [情况2]：期望行为是...

## 不在范围内 (Out of Scope)
- [明确不做的]
```

---

## 访谈检查清单

访谈结束时确认：

- [ ] 每个 JTBD 都有对应 Topics
- [ ] 每个 Topic 有完整 spec
- [ ] 每个 spec 有明确的验收标准（可测试）
- [ ] 边界情况已识别
- [ ] 不在范围内的已明确排除
- [ ] 用户确认 specs 准确反映了他们的需求

---

## 提示词模板

### 开场
```
我来帮你理清需求。在开始之前，我需要先理解你真正想解决的问题。

请回答：
1. 你想解决什么问题？
2. 解决这个问题为什么重要？
3. 解决之后会带来什么改变？

我会通过追问来澄清细节，直到需求完备。
```

### 追问 Topic
```
关于"[刚才提到的点]"，我想多了解一些：
- 具体场景是什么？
- 现在是怎么做的？
- 理想情况应该怎样？
```

### 确认完成
```
需求访谈到这里比较完备了。让我确认一下我们讨论的结果：

[总结每个 Topic 和 验收标准]

这些准确吗？有没有遗漏或需要调整的地方？
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)