paseo-epic

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Paseo Epic

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
or
--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

目标

<one paragraph>
<一段文字>

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.
If
--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.
  1. Mark this phase
    [x]
    .
  2. 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).
  3. Exit cleanly. Don't launch the next phase. Don't poll.
无需Agent。将控制权交还给用户。
  1. 将此阶段标记为
    [x]
    。
  2. 编写交接内容:worktree路径(若已设置)、需测试的内容(下一阶段的验收标准,或此阶段的备注)、恢复方式(满意后执行
    /epic <slug>
    ,或先编辑计划文件)。
  3. 干净退出。不得启动下一阶段。不得轮询。

deliver

deliver(交付)

Inline — see Section 8.
内联处理——见第8节。

Verifying agent output

验证Agent输出

For
refactor
and
implement
:
  1. Read the agent's final activity.
  2. Confirm acceptance: typecheck + tests green, what was touched matches the phase.
  3. Wrong → send a follow-up to the same agent. Don't launch a new one for course-corrections.
  4. 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
阶段:
  1. 阅读Agent的最终活动记录。
  2. 确认验收标准:类型检查通过 + 测试全部通过,修改内容与阶段范围匹配。
  3. 不符合要求 → 向同一Agent发送跟进提示。不得为修正问题启动新的Agent。
  4. 符合要求 → 归档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 — 主分支提交

  1. git status
    — confirm related changes.
  2. git diff
    — review.
  3. Draft a commit message: title <70 chars imperative; body 1–3 sentences why; match repo style (
    git log --oneline -20
    ).
  4. git add <specific files>
    — never
    -A
    or
    .
    .
  5. git commit -m "..."
    (HEREDOC).
  6. Update plan:
    status: delivered
    . Append a Notes line.
  7. Tell user: hash + summary. Ask about push.
  1. git status
    — 确认相关变更。
  2. git diff
    — 审查变更内容。
  3. 编写提交信息:标题(≤70字符,祈使语气);正文(1-3句话说明原因);匹配仓库风格(可参考
    git log --oneline -20
    )。
  4. git add <指定文件>
    — 禁止使用
    -A
    或
    .
    。
  5. git commit -m "..."
    (使用HEREDOC格式)。
  6. 更新计划文件:
    status: delivered
    。在备注中追加一行记录。
  7. 告知用户:提交哈希 + 摘要。询问是否推送。

Mode B — worktree → PR + merge

模式B — worktree → PR + 合并

  1. Commit cleanly in the worktree. One tidy commit per logical change. Match repo style.
  2. 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.
  3. Push the branch —
    git -C <worktree> push -u origin <branch-from-frontmatter>
    .
  4. 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
    .
  5. 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
    .
  6. 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
  7. Archive the worktree via Paseo. Frontmatter:
    status: delivered
    ,
    worktree: null
    . Append a Notes line.
  1. 在worktree中干净提交:每个逻辑变更对应一个整洁的提交。匹配仓库风格。
  2. 若落后于主分支则进行Rebase:启动加载rebase技能的Agent。提供者来自
    impl
    。提示内容:基于origin/main进行rebase,根据意图解决冲突(不得单方面接受某一方的内容),确认类型检查和测试仍全部通过,不得推送。
  3. 推送分支 —
    git -C <worktree> push -u origin <前置元数据中的分支名>
    。
  4. 创建PR — 使用
    gh pr create
    ,摘要来自计划文件的目标和阶段,测试计划来自验收标准行。记录URL → 写入前置元数据
    pr:
    。状态更新为
    pr-open
    。
  5. 监控CI:要么直接监控(
    gh pr checks <n> --watch
    ),要么启动加载fix-build技能的fix-build agent。提供者来自
    impl
    。提示内容:推动PR至CI通过:当检查失败时,读取失败日志,修复问题,推送,重复此过程。禁止合并——由你决定时机。 CI通过后:追加备注,前置元数据
    status: ready-to-merge
    。
  6. CI通过后合并 — 询问用户(
    AskUserQuestion
    :压缩合并/重定基合并/普通合并/等待)。从最近合并的PR中读取仓库惯例(
    gh pr list --state merged -L 5 --json mergeCommit,title
    )。
    bash
    gh pr merge <n> --squash --delete-branch
  7. 通过Paseo归档worktree。前置元数据:
    status: delivered
    ,
    worktree: null
    。在备注中追加一行记录。

Mode C — worktree → cherry-pick

模式C — worktree → cherry-pick

  1. Commit cleanly in the worktree (single clean commit per logical change).
  2. From the main checkout (don't
    cd
    ):
    git cherry-pick <sha>
    . For multiple:
    git cherry-pick <oldest>..<newest>
    .
  3. Conflicts → stop, tell the user. Don't auto-resolve.
  4. Archive the worktree via Paseo. Frontmatter:
    status: delivered
    ,
    worktree: null
    . Ask about push.

  1. 在worktree中干净提交(每个逻辑变更对应一个整洁的提交)。
  2. 在主分支检出目录中执行(无需
    cd
    ):
    git cherry-pick <提交哈希>
    。多个提交则使用:
    git cherry-pick <最早提交>..<最新提交>
    。
  3. 若出现冲突 → 停止操作,告知用户。禁止自动解决冲突。
  4. 通过Paseo归档worktree。前置元数据:
    status: delivered
    ,
    worktree: null
    。询问是否推送。

Resumability

可恢复性

The user can interrupt or kill at any phase. New invocation:
  1. Find the plan by slug (or most recently updated).
  2. Read frontmatter
    status
    and the first non-done phase.
  3. 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.
用户可在任意阶段中断或终止任务。重新调用时:
  1. 通过slug查找计划文件(或使用最近更新的文件)。
  2. 读取前置元数据中的
    status
    和第一个未完成阶段。
  3. 从对应阶段恢复任务。
交付阶段中途恢复:
  • 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
    。
  • 直接推送到主分支。