paseo-epic

Paseo Epic

繁复流程编排器。将研究 → 规划 → 实施 → 交付作为一个可恢复的流程运行。~/.paseo/plans/<slug>.md 中的计划文件是真实信息的唯一来源，即使上下文压缩后也会保留。

这通常会运行数小时，常常会持续一整夜。等 Agent 开始工作时，你就无法再与用户重新讨论意图了。在任何规划 Agent 启动前，先从对话中提取用户已经提出的需求——行为、“为什么”、UX 规则、约束——并将它们作为不可变内容写入计划。后续所有环节（规划器、对抗性审查者、实施者）都围绕这些需求进行优化，而不是重新讨论它们。

用户的请求： $ARGUMENTS

前置条件

这是一个 Paseo 技能。先加载 paseo 技能——它包含运行表面（工作树、Agent、等待、心跳、偏好）。你启动的每个 Agent 也会读取它。

选择任何提供方之前，先读取 ~/.paseo/orchestration-preferences.json。读取该文件之前，不要创建规划器、审查者、研究员、实施者或审计员 Agent。

不要使用你自己的子 Agent。 此技能中的所有 Agent 都是通过 Paseo MCP 启动的 Paseo Agent。你的运行框架原生子 Agent 栈不适用于此处。

角色和阶段类型的术语表位于此技能附带的角色参考文档中（references/roles.md）。

模式

• 默认：对话式。详细询问，在阶段之间设置关卡，交付前先征求同意。
• --autopilot：不详细询问、不设关卡，一路运行至交付。适用于通宵工作。
• --worktree：在新的工作树中隔离工作。

硬性规则

• 计划文件是真实信息的唯一来源。 每个阶段开始前都重新读取。
• 只有你可以写入计划文件。 Agent 不得修改它。
• 需求不可变。 用户陈述的行为、UX、“这样设计的原因”和验收标准，都必须在任何规划器运行前写入计划的 Requirements 区块，之后不得更改。技术计划（阶段、顺序、方案）可围绕它们调整。规划器和审查者可以质疑 HOW，但不能质疑 WHAT 或 WHY。
• 只有满足每条需求，Epic 才算完成。 计划最后必须包含一项轻量检查，依据交付的代码审查 Requirements 区块中的每条内容。如果有任何未满足项，编排器都必须循环回去进行修复，然后再交付——--autopilot 也不例外。
• 每个 Agent 的提供方都来自编排偏好设置——根据角色类别匹配。
• 只能通过 Paseo 使用工作树。 绝不能自行运行 git worktree add。
• Agent 不得提交代码。 交付在交付阶段进行。
• 描述问题，而不是解决方案。 告诉 Agent 哪些内容损坏或需要处理；让它们自行决定如何处理。提示中不要包含具体行号或代码片段。
• 每个阶段只安排一个 Agent。 如果某个阶段需要两个 Agent，说明规划器拆分阶段的方式有误。
• 不要轮询 Agent。 正确等待它们完成。

流程

Preferences → [Worktree] → Research → Capture intent → [Grill] → Plan → Adversarial review → [Confirm] → Implement → Deliver
onboard if                            always           ^^^^^^^                               ^^^^^^^^^
missing                                                default mode                          default mode

---

0. 偏好设置（启动前）

读取 ~/.paseo/orchestration-preferences.json。/epic 会从以下提供方类别中分派任务：

• planning — 起草并审查技术计划
• research — 在规划前调查代码
• impl — 编写代码（重构、实施）
• ui — 实施样式／布局调整
• audit — 只读验证，包括最终的轻量需求检查

如果文件缺失，或上述任一类别未设置，则引导用户完成一次设置。使用 list_providers 和 list_models 显示候选项，用一行说明每个类别，并使用 AskUserQuestion 为每个类别收集一个提供方。将用户选择直接写入 ~/.paseo/orchestration-preferences.json。

在 /epic 将使用的每个类别都设置完成之前，不要继续执行此步骤之后的内容。--autopilot 模式下也适用此规则——自动驾驶模式无法在提供方未知时启动。

如果文件内容完整，则不作说明，继续执行。

---

1. 自行调研

先阅读代码。搜索相关区域，阅读 2–4 个关键文件，了解当前结构。

如果涉及 ≥3 个包或架构变更，请启动一到两个研究员 Agent，每个 Agent 负责一个范围。使用 research 偏好指定的提供方。告诉每位研究员阅读角色参考文档以了解其职责，阅读分配给他们的区域，并报告相关文件、类型、模式和注意事项。不要提供解决方案，也不要修改文件。

用 2–3 句话向用户说明你自己的理解。

2. Worktree（如果使用 --worktree）

通过 Paseo 创建 worktree。记录返回的路径和分支——它们将写入计划的 frontmatter。

3. 明确意图（始终执行）

在任何规划 Agent 运行之前，先将用户已提供的信息提炼为具体的需求列表。即使使用 --autopilot，也必须执行此步骤——这是进一步提问的基础，而不是可以省略的环节。

从触发此技能的对话中提取：已描述的行为、UX 规则、这样设计的原因、约束、必须保持不变的内容、用户明确接受或拒绝的事项，以及验收标准（说明“工作已完成”的具体、可测试条件）。每项写成简短的祈使句。宁可纳入得更全面一些——只要用户提到某项行为、约束或成功条件，就应列入。

在第 6 步写入文件时，直接将这些条目放入计划中的 ## Requirements (immutable) 区块。之后每个 Agent 都会将它们视为固定输入，最终检查也会据此进行审核。

如果用户只提供了产品或 UX 需求，没有提供技术方向，也没有关系。将产品需求和验收标准作为不可变内容记录下来。技术计划由规划者设计，并由审查者提出质疑。

4. 进一步提问（除非使用 --autopilot）

使用 AskUserQuestion。一次只问一个问题，并说明推荐选项；按深度优先的顺序逐一理清分支。绝不询问可通过代码解答的问题。每问 3–4 个问题后，总结已确定的决策。

用户在此过程中明确的任何事项都将成为需求，并添加到不可变区块中。

待所有分支都已理清，或用户表示“继续”时，停止提问。

5. 制定计划并进行对抗性审查

启动规划者

持续协作——不断迭代，不要在收到首个回复后就归档。使用 planning 偏好指定的提供方。

提示其：

• 阅读角色参考文档，熟悉相关术语。
• 将 Objective 和 Requirements (immutable) 区块作为固定输入。技术计划应围绕这些内容进行优化，不得重新设计。如果某项需求看起来不合理，应在聊天中指出，不要暗中绕开。
• 优先考虑重构：如果现有代码无法支持变更，应先规划结构调整，再实现功能。“接线”“胶合”“集成”之类的阶段通常意味着遗漏了上游重构。
• 在聊天中简洁回复，每个阶段一行；不要写入磁盘。

挑战规划者

发送后续问题。针对边缘情况、其他执行顺序、最小可交付范围，以及应改为重构的附加阶段提出质疑。质疑应聚焦于如何实现——阶段划分、顺序和技术方案。Requirements 区块不可更改。持续迭代，直到计划清晰明确。

启动计划审查者

使用 planning 偏好指定的提供方。提示其：

• 阅读角色参考文档。
• 阅读规划者的草案和 Requirements 区块。
• 对技术计划提出质疑：附加式改动、遗漏的边缘情况、过度设计、顺序错误、隐藏依赖。要求提供替代方案，并权衡取舍。
• 将 Requirements 区块视为固定内容。如果某项需求看起来不合理，应向协调者提出标记，不要提出悄然删减或弱化该需求的替代计划。

向用户呈现权衡

绝不要展示原始规划器输出。要呈现选项：

规划器建议 A → B → C（工作切片最快，但会延后重构）。 审查者建议 B → A → C（先重构，速度较慢但更整洁）。 选哪个？

使用 AskUserQuestion。如果用户选择不同的方案，就迭代调整规划器。

计划锁定后，归档规划器和计划审查者。

6. 编写计划

保存到 ~/.paseo/plans/<slug>.md：

---
task: <slug>
status: not-started
worktree: <abs path or null>
branch: <branch or null>
pr: null
created: <ISO>
updated: <ISO>
---

# <Title>

## Objective

<one paragraph>

## Requirements (immutable)

What the user has stated. Behaviors, UX rules, the "why," constraints,
and acceptance criteria (testable conditions for "done").
Captured in step 3 (and extended by the grill in step 4).
This block does not change during planning, review, or implementation.
The final check before deliver audits every bullet here.

- <bullet>
- <bullet>

## Notes

- <ISO> orchestrator: <freeform>

## Phases

- [ ] **Phase 1** · <type> · <short name>
      Acceptance: <one line>

- [ ] **Phase N** · verify · requirements + acceptance audit
- [ ] **Phase N+1** · gate · user smoke test
- [ ] **Phase N+2** · deliver · <commit | PR + merge | cherry-pick>

阶段类型：refactor、implement、verify、gate、deliver。验证变体以内联形式编写：verify · qa、verify · spec、verify · review。参见角色参考。

状态标记：[ ] 未开始，[~] 进行中，[x] 已完成，[!] 已阻塞。

7. 确认（默认模式）

展示阶段列表（不要展示文件内容——他们会自行阅读）。用 2–3 句话说明。等待。

如果是 --autopilot：跳过。

---

8. 实施

循环：找到下一个未完成阶段 → 标记为 [~] → 按类型分派 → 等待 → 验证 → 标记为 [x] → 重复。

在以下情况下停止：到达 gate 阶段、所有阶段均为 [x]，或某个阶段被标记为 [!] 且无法解除阻塞。

按阶段类型分派

refactor

启动一个重构者。使用 impl 中指定的提供方（仅涉及样式的调整则使用 ui）。如果已设置 cwd，则使用工作树路径。告知它：

• 阅读角色参考并加载其中提到的技能。
• 阅读计划文件，包括 Requirements（immutable）区块。范围为第 N 阶段；验收标准已固定在该阶段中。
• 调整结构，不添加功能：前后行为必须相同。现有测试必须保持通过。如果缺少一致性测试，则添加一个。
• 完成后：类型检查通过，相关测试通过。不要提交。不要更新计划。

implement

启动一个 impl Agent。使用 impl 中指定的提供方（仅涉及样式则使用 ui）。如果已设置 cwd，则使用工作树路径。告知它：

• 阅读角色参考并加载其中提到的技能。
• 阅读计划文件，包括 Requirements（immutable）区块。范围为第 N 阶段。Requirements 是约束，不是建议——按其要求实现。
• 按路径阅读所有与计划相关的仓库文档。
• TDD：先编写失败的测试，再让测试通过。
• 如果现有结构无法容纳此变更，应提出异议，而不是勉强拼凑——应先安排一个重构阶段。
• 完成后：类型检查通过，所有涉及的测试均通过。不要提交。不要更新计划。

verify

根据 verify · 后的变体启动相应的审计者。使用 audit 中指定的提供方。角色参考中的变体表会说明审计者需要加载什么以及需要输出什么。只读——不做修改。

gate

不启动 Agent。交由用户处理。

1. 将此阶段标记为 [x]。
2. 编写交接说明：工作树路径（如果已设置）、需要测试的内容（下一阶段的验收标准，或此阶段的 Notes）、如何恢复（满足条件后执行 /epic <slug>，或先编辑计划）。
3. 正常退出。不要启动下一阶段。不要轮询。

deliver

内联处理——参见第 9 节。

验证 Agent 输出

对于 refactor 和 implement：

1. 阅读 Agent 的最终活动记录。
2. 确认验收情况：类型检查和测试均通过，且实际修改内容符合该阶段的要求。
3. 不符合 → 向同一个 Agent 发送后续指示。不要为纠正方向而启动新的 Agent。
4. 符合 → 归档。

对于 verify：

• 通过 → 将已审计阶段标记为 [x]，继续推进。
• 有问题 → 将发现的问题追加到 Notes。不要将阶段标记为已完成。可以将发现的问题作为新的验收标准发送给 impl Agent；如果情况不明确，则向用户说明。

用户插话时

• 对正在运行的 Agent 提供反馈 → 转发给它。
• 更改计划 → 编辑计划文件（添加、删除或重新排序），告知用户变更内容，然后继续。
• “停止”/“终止” → 归档正在运行的 Agent，总结当前状态，然后等待。
• 提出新问题 → 简短回答，然后继续。

计划文件可让新的协调者在用户终止当前协调者并重新调用后接手——及时将所有重要信息写入 Notes。

---

9. 交付

阅读 frontmatter 以选择模式：

worktree: null   → Mode A: main commit
worktree: <path> → Mode B (PR) or Mode C (cherry-pick); ask if not specified

绝不要直接推送到 main。未经明确许可，绝不要强制推送。CI 通过前绝不要合并。通过 Paseo 归档工作树，绝不要使用 git worktree remove。

模式 A — 主提交

1. git status — 确认相关更改。
2. git diff — 检查差异。
3. 起草提交说明：标题少于 70 个字符，使用祈使句；正文用 1–3 句话说明原因；遵循仓库风格（git log --oneline -20）。
4. git add <specific files> — 绝不要使用 -A 或 .。
5. git commit -m "..."（HEREDOC）。
6. 更新计划：status: delivered。追加一行 Notes。
7. 告知用户：哈希值 + 摘要。询问是否推送。

模式 B — 工作树 → PR + 合并

1. 在工作树中干净地提交。 每个逻辑更改只提交一个整洁的提交。遵循仓库风格。
2. 如果落后于 main，则进行变基。 启动一个 Agent。使用 impl 中的 Provider。让它变基到 origin/main，按更改意图解决冲突（绝不要不加判断地接受某一方的全部更改），确认类型检查和测试仍然通过，不要推送。
3. 推送分支 — git -C <worktree> push -u origin <branch-from-frontmatter>。
4. 创建 PR — 使用计划中的 Objective + Phases 作为摘要，使用验收条目作为测试计划，运行 gh pr create。记录 URL → frontmatter pr:。状态 → pr-open。
5. 跟进 PR。 启动一个 Agent，推动 PR 达到绿色状态。使用 impl 中的 Provider。让它加载 /babysit-pr，使用 create_heartbeat 唤醒机制，而不是轮询；将阅读 PR 评审作为工作的一部分；处理 Greptile 自动评审评论，除非它们有误或已过时；持续修复、推送并重新检查，直到所有检查都通过。不要合并——由你决定。 CI 通过且可处理的评审意见均已解决后：追加 Notes，frontmatter status: ready-to-merge。
6. 检查通过后合并 — 询问用户（AskUserQuestion：squash / rebase / merge / wait）。通过近期已合并的 PR 了解仓库惯例（gh pr list --state merged -L 5 --json mergeCommit,title）。

   gh pr merge <n> --squash --delete-branch
   

7. 通过 Paseo 归档工作树。 Frontmatter：status: delivered、worktree: null。追加一行 Notes。

模式 C — 工作树 → cherry-pick

1. 在工作树中干净地提交（每个逻辑更改只提交一个整洁的提交）。
2. 从主检出目录执行（不要 cd）：git cherry-pick <sha>。多个提交时：git cherry-pick <oldest>..<newest>。
3. 遇到冲突 → 停止并告知用户。不要自动解决。
4. 通过 Paseo 归档工作树。Frontmatter：status: delivered、worktree: null。询问是否推送。

---

可恢复性

用户可以在任何阶段中断或终止操作。新一轮调用时：

1. 按 slug（或最近更新的计划）查找计划。
2. 读取 frontmatter 中的 status 和第一个未完成阶段。
3. 从对应阶段继续。

交付过程中的恢复：

• status: pr-open + pr: <url> → 恢复 CI 监控。
• status: ready-to-merge → 再次询问用户是否合并。
• status: delivered + worktree: <path> → 工作树尚未归档，进行归档。

失败模式

• 跳过需求收集环节，因为跳过了深入讨论。Requirements 区块是底线；深入讨论只会扩展它。
• 让对抗性评审削弱用户已确定的需求。评审者可以完善技术计划，但不能重新讨论意图。
• 把各阶段当作必须逐项完成的清单。它们是关卡。推进前先验证。
• 在工作树模式下忘记将 Agent 的 cwd 设置为工作树路径。
• 向用户重复解释计划。他们已与你共同撰写计划。按阶段编号引用即可。
• 没有正确等待，而是轮询 Agent。
• 自己编辑代码。你负责协调，Agent 负责实现。
• 在工作树实际归档之前就标记 status: delivered。
• 直接推送到 main。