paseo-epic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paseo Epic

Heavy-ceremony orchestrator. Runs research → plan → implement → deliver as one resumable flow. The plan file at

~/.paseo/plans/<slug>.md

is the source of truth and survives compaction.

User's request: $ARGUMENTS

重型流程编排器。将调研→规划→实施→交付作为一个可恢复的流程运行。位于

~/.paseo/plans/<slug>.md

的计划文件是唯一可信来源，且在压缩后仍会保留。

用户请求: $ARGUMENTS

Prerequisites

前置条件

Read the paseo skill — it carries the surface (worktrees, agents, waiting, scheduling, preferences). Every agent you spawn reads it too.

The role and phase-type vocabulary lives in the roles reference shipped with this skill (

references/roles.md

阅读paseo技能文档——它涵盖了基础内容（worktrees、agents、等待机制、调度、偏好设置）。你启动的每个Agent都会读取该文档。

角色和阶段类型的术语定义包含在本技能附带的角色参考文档中（

references/roles.md

）。

Modes

模式

Default: conversational. Grills, gates between phases, ask before deliver.
```
--autopilot
```
: no grills, no gates, run through deliver. For all-night work.
```
--worktree
```
: isolate the work in a new worktree.
```
--no-grill
```
: skip clarifying questions; keep gates.

默认模式：对话式。各阶段间包含质询（Grill）和关卡（Gate），交付前会询问用户。
```
--autopilot
```
：无质询、无关卡，直接运行至交付阶段。适用于整夜运行的工作。
```
--worktree
```
：在新的worktree中隔离工作内容。
```
--no-grill
```
：跳过澄清问题；保留关卡机制。

Hard rules

硬性规则

The plan file is the source of truth. Re-read before every phase.
You are the only writer to the plan file. Agents don't touch it.
Provider for every agent comes from orchestration preferences — match the role's category.
Worktrees only via Paseo. Never run
```
git worktree add
```
yourself.
Agents do not commit. Delivery happens in the deliver phase.
Describe problems, not solutions. Tell agents what's broken or needed; let them decide how. No specific line numbers or code snippets in prompts.
One agent per phase. If a phase needs two, the planner split it wrong.
Don't poll agents. Wait for them properly.

计划文件是唯一可信来源：每个阶段开始前都要重新读取。
你是唯一可编辑计划文件的角色：Agents不得修改该文件。
每个Agent的提供者来自编排偏好设置——需匹配角色所属类别。
仅通过Paseo创建worktree：禁止自行执行
```
git worktree add
```
命令。
Agents不得提交代码：交付操作仅在交付阶段执行。
描述问题，而非解决方案：告知Agents需要修复的问题或需求；由他们决定实现方式。提示中不得包含具体行号或代码片段。
每个阶段仅分配一个Agent：若某阶段需要两个Agent，说明规划者拆分有误。
不得轮询Agents：需正确等待Agent完成任务。

Flow

流程

[Worktree] → Research → [Grill] → Plan → Adversarial review → [Confirm] → Implement → Deliver
                        ^^^^^^^                                ^^^^^^^^^
                        default mode                           default mode

[Worktree] → 调研 → [质询] → 规划 → 对抗性评审 → [确认] → 实施 → 交付
                        ^^^^^^^                                ^^^^^^^^^
                        默认模式                               默认模式

1. Research yourself

1. 自行开展调研

Read the code first. Grep the relevant area, read 2–4 key files, understand the current shape.

For ≥3 packages or architectural change, spawn one or two researcher agents — each scoped to one area. Provider from the

research

preference. Tell each researcher to read the roles reference for its mandate, read the area you've assigned, and report files / types / patterns / gotchas. No solutions. No edits.

State your own understanding to the user in 2–3 sentences.

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

若涉及≥3个包或架构变更，启动1-2个researcher agents——每个Agent负责一个特定领域。提供者来自

research

偏好设置。告知每个researcher阅读角色参考文档中的职责说明、你分配的领域内容，并汇报文件/类型/模式/潜在问题。不得提供解决方案，不得编辑代码。

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

2. Worktree (if

--worktree

)

2. 创建Worktree（若使用

--worktree

）

Create a worktree via Paseo. Record the returned path and branch — they go into the plan frontmatter.

通过Paseo创建worktree。记录返回的路径和分支——它们将被写入计划文件的前置元数据中。

3. Grill (unless

--no-grill

--autopilot

)

3. 质询环节（除非使用

--no-grill

或

--autopilot

）

Use

AskUserQuestion

. One at a time, recommended option stated, branches resolved depth-first. Never ask code-answerable questions. Every 3–4 questions, summarize resolved decisions.

Stop when branches are resolved or the user says "go".

使用

AskUserQuestion

工具。每次提出一个问题，给出推荐选项，按深度优先原则解决分支问题。禁止询问可通过代码找到答案的问题。每提出3-4个问题后，总结已确定的决策。

当分支问题全部解决或用户说“继续”时停止。

4. Plan with adversarial review

4. 规划与对抗性评审

Spawn a planner

启动planner agent

Persistent — keep iterating, do not archive after the first response. Provider from the

planning

preference.

Prompt it to:

Read the roles reference for vocabulary.
Take the objective and resolved decisions from grill as input.
Think refactor-first: if existing code doesn't accommodate the change, plan the reshape before the feature. Phases like "wire up", "glue", "integrate" usually mean an upstream refactor was missed.
Reply terse, one line per phase, in chat — not to disk.

该Agent需保持持久化——持续迭代，不得在首次响应后归档。提供者来自

planning

偏好设置。

提示内容：

阅读角色参考文档中的术语定义。
将目标和质询环节确定的决策作为输入。
优先考虑重构：若现有代码无法适配变更，需先规划重构，再实现功能。类似“连接”“粘合”“集成”的阶段通常意味着遗漏了上游重构步骤。
回复需简洁，每个阶段用一行文字，在对话中回复——不得写入磁盘。

Challenge it

挑战planner的方案

Send follow-ups. Push on edge cases, alternative orderings, smallest shippable slice, bolt-on phases that should be a refactor instead. Iterate until the plan is sharp.

发送跟进问题。针对边缘情况、备选顺序、最小可交付版本、应改为重构的附加阶段提出质疑。迭代直至规划方案精准可行。

Spawn a plan-reviewer

启动plan-reviewer agent

Provider from the

planning

preference. Prompt it to:

Read the roles reference.
Read the planner's draft.
Challenge it: bolt-ons, missing edge cases, over-engineering, wrong ordering, hidden dependencies. Push for alternatives. Force tradeoffs.

提供者来自

planning

偏好设置。提示内容：

阅读角色参考文档。
阅读planner的草稿方案。
提出质疑：附加阶段、遗漏的边缘情况、过度设计、错误的顺序、隐藏的依赖关系。推动备选方案，强制权衡取舍。

Surface tradeoffs to the user

向用户呈现权衡选项

Never present raw planner output. Surface the choice:

Planner wants A → B → C (working slice fastest, defers refactor). Reviewer argued for B → A → C (refactor first, slower but cleaner). Which?

Use

AskUserQuestion

. Iterate the planner if the user picks differently.

Archive the planner and plan-reviewer once the plan is locked.

不得直接展示planner的原始输出。需呈现选择：

Planner建议顺序为A → B → C（最快产出可用版本，推迟重构）。 Reviewer主张顺序为B → A → C（先重构，速度较慢但代码更整洁）。选择哪种方案？

使用

AskUserQuestion

工具。若用户选择不同方案，需让planner重新迭代。

规划方案锁定后，归档planner和plan-reviewer agents。

5. Write the plan

5. 编写计划文件

Persist to

~/.paseo/plans/<slug>.md

markdown

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

将内容持久化至

~/.paseo/plans/<slug>.md

：

markdown

---
task: <slug>
status: not-started
worktree: <绝对路径或null>
branch: <分支名或null>
pr: null
created: <ISO格式时间>
updated: <ISO格式时间>
---

<Title>

<标题>

Objective

目标

<一段文字>

Notes

备注

<ISO> orchestrator: <freeform>

<ISO格式时间> orchestrator: <自由格式内容>

Phases

阶段

Phase 1 · <type> · <short name> Acceptance: <one line>
Phase N · gate · user smoke test
Phase N+1 · deliver · <commit | PR + merge | cherry-pick>


Phase types: `refactor`, `implement`, `verify`, `gate`, `deliver`. Verify variants written inline: `verify · unslop`, `verify · qa`, `verify · spec`, `verify · review`. See the roles reference.

Status markers: `[ ]` not started, `[~]` in progress, `[x]` done, `[!]` blocked.

阶段1 · <类型> · <简短名称> 验收标准: <一行文字>
阶段N · gate · 用户冒烟测试
阶段N+1 · deliver · <commit | PR + merge | cherry-pick>


阶段类型：`refactor`、`implement`、`verify`、`gate`、`deliver`。`verify`的变体需内联写入：`verify · unslop`、`verify · qa`、`verify · spec`、`verify · review`。详情见角色参考文档。

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

6. Confirm (default mode)

6. 确认环节（默认模式）

Show the phase list (not the file contents — they'll read it). 2–3 sentences. Wait.

--autopilot

: skip.

展示阶段列表（无需展示文件内容——用户会自行查看）。用2-3句话说明。等待用户确认。

若使用

--autopilot

：跳过此环节。

7. Implement

7. 实施阶段

Loop: find next undone phase → mark

[~]

→ dispatch by type → wait → verify → mark

[x]

→ repeat.

Stop when: a

gate

phase is reached, all phases

[x]

, or a phase is

[!]

blocked and you can't unblock it.

循环流程：找到下一个未完成阶段 → 标记为

[~]

→ 按类型分配任务 → 等待完成 → 验证 → 标记为

[x]

→ 重复。

停止条件：到达

gate

阶段、所有阶段标记为

[x]

，或某阶段标记为

[!]

且无法解除阻塞。

Dispatch by phase type

按阶段类型分配任务

refactor

refactor（重构）

Spawn a refactorer. Provider from

impl

(or

ui

for styling-only reshapes). cwd = the worktree path if set. Tell it to:

Read the roles reference and load the skills it names.
Read the plan file. Scope is Phase N; acceptance is pinned there.
Reshape, not feature: behavior identical before and after. Existing tests stay green. Add a parity test if missing.
When done: typecheck pass + relevant tests green. Do not commit. Do not update the plan.

启动refactorer agent。提供者来自

impl

（若仅涉及样式重构则来自

ui

）。工作目录（cwd）= 已设置的worktree路径。提示内容：

阅读角色参考文档并加载指定的技能。
阅读计划文件。范围为第N阶段；验收标准以文件中为准。
仅重构，不添加功能：重构前后行为完全一致。现有测试需保持通过。若缺少对等测试需补充。
完成标准：类型检查通过 + 相关测试全部通过。不得提交代码。不得更新计划文件。

implement

implement（实现）

Spawn an impl agent. Provider from

impl

(or

ui

for styling-only). cwd = the worktree path if set. Tell it to:

Read the roles reference and load the skills it names.
Read the plan file. Scope is Phase N.
Read any plan-relevant repo docs by path.
TDD: failing test first, then make it pass.
If the existing shape doesn't accommodate the change, push back instead of bolting on — a refactor phase should have come first.
When done: typecheck + every test it touched green. Do not commit. Do not update the plan.

启动impl agent。提供者来自

impl

（若仅涉及样式实现则来自

ui

）。工作目录（cwd）= 已设置的worktree路径。提示内容：

阅读角色参考文档并加载指定的技能。
阅读计划文件。范围为第N阶段。
阅读计划相关的仓库文档（按路径指定）。
采用TDD：先编写失败的测试，再实现代码使其通过。
若现有代码结构无法适配变更，需提出反馈而非强行添加——说明应先执行重构阶段。
完成标准：类型检查通过 + 所有涉及的测试全部通过。不得提交代码。不得更新计划文件。

verify

verify（验证）

Spawn an auditor matching the variant after

verify ·

. Provider from

audit

. The roles reference's variant table tells the auditor what to load and what to output. Read-only — no edits.

启动与

verify ·

后变体匹配的auditor agent。提供者来自

audit

。角色参考文档中的变体表会告知auditor需加载的内容和输出要求。仅读取——不得编辑。

gate

gate（关卡）

No agent. Yield to the user.

Mark this phase
```
[x]
```
.
Compose handoff: worktree path (if set), what to test (next phase's acceptance, or this phase's Notes), how to resume (
```
/epic <slug>
```
once satisfied, or edit the plan first).
Exit cleanly. Don't launch the next phase. Don't poll.

无需Agent。将控制权交还给用户。

将此阶段标记为
```
[x]
```
。
编写交接内容：worktree路径（若已设置）、需测试的内容（下一阶段的验收标准，或此阶段的备注）、恢复方式（满意后执行
```
/epic <slug>
```
，或先编辑计划文件）。
干净退出。不得启动下一阶段。不得轮询。

deliver

deliver（交付）

Inline — see Section 8.

内联处理——见第8节。

Verifying agent output

验证Agent输出

For

refactor

and

implement

Read the agent's final activity.
Confirm acceptance: typecheck + tests green, what was touched matches the phase.
Wrong → send a follow-up to the same agent. Don't launch a new one for course-corrections.
OK → archive.

For

verify

Green → mark the audited phase
```
[x]
```
, advance.
Issues → append findings to Notes. Do not mark the phase done. Either send the impl agent the findings as new acceptance, or surface to the user if ambiguous.

对于

refactor

和

implement

阶段：

阅读Agent的最终活动记录。
确认验收标准：类型检查通过 + 测试全部通过，修改内容与阶段范围匹配。
不符合要求 → 向同一Agent发送跟进提示。不得为修正问题启动新的Agent。
符合要求 → 归档Agent。

对于

verify

阶段：

验证通过 → 将被审计的阶段标记为
```
[x]
```
，进入下一阶段。
发现问题 → 将结果追加至备注。不得标记阶段为已完成。要么将发现的问题作为新的验收标准发送给impl agent，若存在歧义则告知用户。

When the user interjects

用户中途干预时的处理

Feedback on a running agent → forward to it.
Plan change → edit the plan file (add/remove/reorder), tell them what changed, continue.
"Stop" / "kill" → archive running agents, summarize state, wait.
New question → answer briefly, continue.

The plan file lets a fresh orchestrator pick up if the user kills you and reinvokes — write everything important to Notes immediately.

对运行中Agent的反馈 → 转发给该Agent。
修改计划 → 编辑计划文件（添加/删除/重新排序阶段），告知用户变更内容，继续执行。
「停止」/「终止」 → 归档运行中的Agent，总结当前状态，等待用户指令。
新问题 → 简要回答，继续执行。

若用户终止并重新调用，新的编排器可通过计划文件恢复任务——需立即将所有重要内容写入备注。

8. Deliver

8. 交付阶段

Read frontmatter to choose mode:

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

Never push to main directly. Never force-push without explicit permission. Never merge before CI is green. Archive worktrees via Paseo, never

git worktree remove

读取前置元数据选择交付模式：

worktree: null   → 模式A：主分支提交
worktree: <路径> → 模式B（PR）或模式C（cherry-pick）；若未指定则询问用户

禁止直接推送到主分支。禁止未经明确许可强行推送。CI未通过前禁止合并。仅通过Paseo归档worktrees，禁止使用

git worktree remove

。

Mode A — main commit

模式A — 主分支提交

```
git status
```
— confirm related changes.
```
git diff
```
— review.
Draft a commit message: title <70 chars imperative; body 1–3 sentences why; match repo style (
```
git log --oneline -20
```
).
```
git add <specific files>
```
— never
```
-A
```
or
```
.
```
.
```
git commit -m "..."
```
(HEREDOC).
Update plan:
```
status: delivered
```
. Append a Notes line.
Tell user: hash + summary. Ask about push.

```
git status
```
— 确认相关变更。
```
git diff
```
— 审查变更内容。
编写提交信息：标题（≤70字符，祈使语气）；正文（1-3句话说明原因）；匹配仓库风格（可参考
```
git log --oneline -20
```
）。
```
git add <指定文件>
```
— 禁止使用
```
-A
```
或
```
.
```
。
```
git commit -m "..."
```
（使用HEREDOC格式）。
更新计划文件：
```
status: delivered
```
。在备注中追加一行记录。
告知用户：提交哈希 + 摘要。询问是否推送。

Mode B — worktree → PR + merge

模式B — worktree → PR + 合并

Commit cleanly in the worktree. One tidy commit per logical change. Match repo style.
Rebase if behind main. Spawn an agent that loads the rebase skill. Provider from
```
impl
```
. Tell it to rebase onto origin/main, resolve conflicts by intent (never blanket-accept one side), confirm typecheck and tests still pass, do not push.

Push the branch —

git -C <worktree> push -u origin <branch-from-frontmatter>

Open the PR —
```
gh pr create
```
with summary from plan Objective + Phases and test plan from acceptance lines. Capture URL → frontmatter
```
pr:
```
. Status →
```
pr-open
```
.
Monitor CI. Either watch directly (
```
gh pr checks <n> --watch
```
), or spawn a fix-build agent that loads the fix-build skill. Provider from
```
impl
```
. Tell it to drive the PR to green: when checks fail, read failure logs, fix, push, repeat. Don't merge — your call. When green: append Notes, frontmatter
```
status: ready-to-merge
```
.
Merge when green — ask the user (
```
AskUserQuestion
```
: squash / rebase / merge / wait). Read repo convention from recent merged PRs (
```
gh pr list --state merged -L 5 --json mergeCommit,title
```
).
bash
```
gh pr merge <n> --squash --delete-branch
```
Archive the worktree via Paseo. Frontmatter:
```
status: delivered
```
,
```
worktree: null
```
. Append a Notes line.

在worktree中干净提交：每个逻辑变更对应一个整洁的提交。匹配仓库风格。
若落后于主分支则进行Rebase：启动加载rebase技能的Agent。提供者来自
```
impl
```
。提示内容：基于origin/main进行rebase，根据意图解决冲突（不得单方面接受某一方的内容），确认类型检查和测试仍全部通过，不得推送。

推送分支 —

git -C <worktree> push -u origin <前置元数据中的分支名>

。

创建PR — 使用
```
gh pr create
```
，摘要来自计划文件的目标和阶段，测试计划来自验收标准行。记录URL → 写入前置元数据
```
pr:
```
。状态更新为
```
pr-open
```
。
监控CI：要么直接监控（
```
gh pr checks <n> --watch
```
），要么启动加载fix-build技能的fix-build agent。提供者来自
```
impl
```
。提示内容：推动PR至CI通过：当检查失败时，读取失败日志，修复问题，推送，重复此过程。禁止合并——由你决定时机。 CI通过后：追加备注，前置元数据
```
status: ready-to-merge
```
。
CI通过后合并 — 询问用户（
```
AskUserQuestion
```
：压缩合并/重定基合并/普通合并/等待）。从最近合并的PR中读取仓库惯例（
```
gh pr list --state merged -L 5 --json mergeCommit,title
```
）。
bash
```
gh pr merge <n> --squash --delete-branch
```
通过Paseo归档worktree。前置元数据：
```
status: delivered
```
，
```
worktree: null
```
。在备注中追加一行记录。

Mode C — worktree → cherry-pick

模式C — worktree → cherry-pick

Commit cleanly in the worktree (single clean commit per logical change).

From the main checkout (don't

cd

git cherry-pick <sha>

. For multiple:

git cherry-pick <oldest>..<newest>

Conflicts → stop, tell the user. Don't auto-resolve.
Archive the worktree via Paseo. Frontmatter:
```
status: delivered
```
,
```
worktree: null
```
. Ask about push.

在worktree中干净提交（每个逻辑变更对应一个整洁的提交）。

在主分支检出目录中执行（无需

cd

）：

git cherry-pick <提交哈希>

。多个提交则使用：

git cherry-pick <最早提交>..<最新提交>

。

若出现冲突 → 停止操作，告知用户。禁止自动解决冲突。
通过Paseo归档worktree。前置元数据：
```
status: delivered
```
，
```
worktree: null
```
。询问是否推送。

Resumability

可恢复性

The user can interrupt or kill at any phase. New invocation:

Find the plan by slug (or most recently updated).
Read frontmatter
```
status
```
and the first non-done phase.
Resume from the matching phase.

Mid-deliver resumption:

```
status: pr-open
```
+
```
pr: <url>
```
→ resume CI monitoring.
```
status: ready-to-merge
```
→ ask the user to merge again.
```
status: delivered
```
+
```
worktree: <path>
```
→ worktree wasn't archived, do that.

用户可在任意阶段中断或终止任务。重新调用时：

通过slug查找计划文件（或使用最近更新的文件）。
读取前置元数据中的
```
status
```
和第一个未完成阶段。
从对应阶段恢复任务。

交付阶段中途恢复：

```
status: pr-open
```
+
```
pr: <URL>
```
→ 恢复CI监控。
```
status: ready-to-merge
```
→ 再次询问用户是否合并。
```
status: delivered
```
+
```
worktree: <路径>
```
→ worktree未归档，执行归档操作。

Failure modes

失败模式

Treating phases as a checklist to grind through. They're gates. Verify before advancing.
Forgetting to set the agent's cwd to the worktree path in worktree mode.
Re-explaining the plan to the user. They wrote it with you. Reference phases by number.
Polling agents instead of waiting properly.
Editing code yourself. You orchestrate. Agents implement.
Marking
```
status: delivered
```
before the worktree is actually archived.
Pushing to main directly.

将阶段视为需快速完成的清单：阶段是关卡，推进前必须验证。
在worktree模式下忘记将Agent的工作目录设置为worktree路径。
向用户重复解释计划：计划是与用户共同制定的，只需通过阶段编号引用即可。
轮询Agents而非正确等待。
自行编辑代码：你的职责是编排，由Agents负责实现。
worktree实际未归档前就标记
```
status: delivered
```
。
直接推送到主分支。

paseo-epic

Original

Translation

Paseo Epic

Paseo Epic

Prerequisites

前置条件

Modes

模式

Hard rules

硬性规则

Flow

流程

1. Research yourself

1. 自行开展调研

2. Worktree (if --worktree)

2. 创建Worktree（若使用--worktree）

3. Grill (unless --no-grill or --autopilot)

3. 质询环节（除非使用--no-grill或--autopilot）

4. Plan with adversarial review

4. 规划与对抗性评审

Spawn a planner

启动planner agent

Challenge it

挑战planner的方案

Spawn a plan-reviewer

启动plan-reviewer agent

Surface tradeoffs to the user

向用户呈现权衡选项

5. Write the plan

5. 编写计划文件

<Title>

<标题>

Objective

目标

Notes

备注

Phases

阶段

6. Confirm (default mode)

6. 确认环节（默认模式）

7. Implement

7. 实施阶段

Dispatch by phase type

按阶段类型分配任务

refactor

refactor（重构）

implement

implement（实现）

verify

verify（验证）

gate

gate（关卡）

deliver

deliver（交付）

Verifying agent output

验证Agent输出

When the user interjects

用户中途干预时的处理

8. Deliver

8. 交付阶段

Mode A — main commit

模式A — 主分支提交

Mode B — worktree → PR + merge

模式B — worktree → PR + 合并

Mode C — worktree → cherry-pick

模式C — worktree → cherry-pick

Resumability

可恢复性

Failure modes

失败模式

2. Worktree (if
`--worktree`
)

2. 创建Worktree（若使用
`--worktree`
）

3. Grill (unless
`--no-grill`
or
`--autopilot`
)

3. 质询环节（除非使用
`--no-grill`
或
`--autopilot`
）