// Heavy-ceremony orchestration for big work — research, planning, adversarial review, phased implementation, audit, delivery. Use when the user says "epic", "long task", "build this end to end", or wants a feature that runs all night.
| name | paseo-epic |
| description | Heavy-ceremony orchestration for big work — research, planning, adversarial review, phased implementation, audit, delivery. Use when the user says "epic", "long task", "build this end to end", or wants a feature that runs all night. |
| user-invocable | true |
| argument-hint | [--autopilot] [--worktree] <task> |
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.
This usually runs for hours, often overnight. By the time agents are working, you cannot re-litigate intent with the user. Capture the requirements they have already given you in conversation — behaviors, the "why," UX rules, constraints — and write them into the plan as immutable before any planning agent spins up. Everything downstream (planner, adversarial reviewer, implementers) optimizes around those requirements; it does not relitigate them.
User's request: $ARGUMENTS
This is a Paseo skill. Load the paseo skill first — it carries the surface (worktrees, agents, waiting, scheduling, preferences). Every agent you spawn reads it too.
Do not use your own subagents. All agents in this skill are Paseo agents, spawned through the Paseo MCP. Your harness's native subagent stack is not in play here.
The role and phase-type vocabulary lives in the roles reference shipped with this skill (references/roles.md).
--autopilot: no grills, no gates, run through deliver. For all-night work.--worktree: isolate the work in a new worktree.--autopilot too.git worktree add yourself.Preferences → [Worktree] → Research → Capture intent → [Grill] → Plan → Adversarial review → [Confirm] → Implement → Deliver
onboard if always ^^^^^^^ ^^^^^^^^^
missing default mode default mode
Read ~/.paseo/orchestration-preferences.json. /epic dispatches across these provider categories:
planning — drafts and reviews the technical planresearch — surveys the code before planningimpl — writes code (refactor, implement)ui — implements styling/layout passesaudit — read-only verification, including the final lightweight requirements checkIf the file is missing or any of these categories is unset, walk the user through it once. Use list_providers and list_models to surface candidates, explain each category in one line, and use AskUserQuestion to collect a provider per category. Persist their choices straight to ~/.paseo/orchestration-preferences.json.
Do not proceed past this step until every category /epic will use is set. This applies under --autopilot too — autopilot cannot start without known providers.
If the file is complete, say nothing and continue.
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.
--worktree)Create a worktree via Paseo. Record the returned path and branch — they go into the plan frontmatter.
Before any planning agent runs, distill what the user has already told you into a concrete Requirements list. This step runs even under --autopilot — it is the floor that grilling extends, not replaces.
Pull from the conversation that led to this skill being invoked: described behaviors, UX rules, the "why this works this way," constraints, what must not change, what the user explicitly accepted or rejected, and the acceptance criteria (concrete, testable conditions that say "the work is done"). Write each as a short imperative bullet. Lean inclusive — if the user mentioned it as a behavior, constraint, or success condition, it goes in.
Drop these bullets straight into the plan's ## Requirements (immutable) block when you write the file in step 6. They become the input every downstream agent reads as fixed, and the bar the final check audits against.
If the user has only given product/UX requirements and no technical direction, that is fine. Capture the product requirements and acceptance criteria as immutable. The technical plan is what the planner gets to design and the reviewer gets to challenge.
--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.
Anything the user resolves here becomes a Requirement and gets added to the immutable block.
Stop when branches are resolved or the user says "go".
Persistent — keep iterating, do not archive after the first response. Provider from the planning preference.
Prompt it to:
Send follow-ups. Push on edge cases, alternative orderings, smallest shippable slice, bolt-on phases that should be a refactor instead. Keep the challenge on HOW — phases, ordering, technical approach. The Requirements block is not on the table here. Iterate until the plan is sharp.
Provider from the planning preference. Prompt it to:
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.
Persist to ~/.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>
Phase types: refactor, implement, verify, gate, deliver. Verify variants written inline: verify · qa, verify · spec, verify · review. See the roles reference.
Status markers: [ ] not started, [~] in progress, [x] done, [!] blocked.
Show the phase list (not the file contents — they'll read it). 2–3 sentences. Wait.
If --autopilot: skip.
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.
Spawn a refactorer. Provider from impl (or ui for styling-only reshapes). cwd = the worktree path if set. Tell it to:
Spawn an impl agent. Provider from impl (or ui for styling-only). cwd = the worktree path if set. Tell it to:
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.
No agent. Yield to the user.
[x]./epic <slug> once satisfied, or edit the plan first).Inline — see Section 9.
For refactor and implement:
For verify:
[x], advance.The plan file lets a fresh orchestrator pick up if the user kills you and reinvokes — write everything important to Notes immediately.
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.
git status — confirm related changes.git diff — review.git log --oneline -20).git add <specific files> — never -A or ..git commit -m "..." (HEREDOC).status: delivered. Append a Notes line.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.git -C <worktree> push -u origin <branch-from-frontmatter>.gh pr create with summary from plan Objective + Phases and test plan from acceptance lines. Capture URL → frontmatter pr:. Status → pr-open.gh pr checks <n> --watch), or spawn an agent to babysit the build. 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.AskUserQuestion: squash / rebase / merge / wait). Read repo convention from recent merged PRs (gh pr list --state merged -L 5 --json mergeCommit,title).
gh pr merge <n> --squash --delete-branch
status: delivered, worktree: null. Append a Notes line.cd): git cherry-pick <sha>. For multiple: git cherry-pick <oldest>..<newest>.status: delivered, worktree: null. Ask about push.The user can interrupt or kill at any phase. New invocation:
status and the first non-done 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.status: delivered before the worktree is actually archived.Cut a beta release of Paseo. Use when the user says "release beta", "cut a beta", "ship a beta", "beta release", or "/release-beta". Betas are silent release candidates — no changelog, no website move.
Cut a stable release of Paseo (fresh patch or promote from beta). Use when the user says "release stable", "ship stable", "promote", "release:patch", "release:promote", or "/release-stable".
Paseo reference for managing agents and worktrees. Load whenever you need to create agents, send them prompts, or manage worktrees.
Spin up a single agent as an advisor — second opinion on the current task. Use when the user says "advisor", "second opinion", "what does X think", or wants an outside take without delegating the work itself.
Form a committee of two high-reasoning agents to step back, do root cause analysis, and produce a plan. Use when stuck, looping, tunnel-visioning, or facing a hard planning problem.
Hand off the current task to another agent with full context. Use when the user says "handoff", "hand off", "hand this to", or wants to pass work to another agent.