Hands-off epics

An epic is a tracking issue whose sub-issues are wired by dependency edges. Shepherd spawns a session per ready child, collects their PRs on a shared integration branch, and lands everything as one final PR. With the right automation defaults, an epic drains end-to-end without operator intervention — it only stops on a genuine blocker.

This page documents the best-practice automation-pane settings for that, and what will still stop the epic (so hands-off never means unsafe).

Don’t have an epic yet? See Authoring an epic to structure one Shepherd recognizes, then come back here to drain it.

The automation pane holds repo-wide defaults — “Repo automation”, not this task alone. The “Apply hands-off defaults” button on the Epic panel writes these same repo-wide defaults, so they apply to every task in the repo, not only the epic you launched it from.

Recommended settings

Open the automation pane (the ⚙ automation pill) and set:

Setting	Recommended	Why
Autopilot	On	Drives each session through routine stops toward a PR instead of handing back to you.
Full-auto merge	On	The merge train lands each ready PR automatically. Turning it on forces Draft mode off (they are mutually exclusive).
Critic	On	Auto code-review of every push, in parallel with CI (on by default). Required for Auto-Address.
Auto-Address	On	Feeds critic findings back to the agent automatically, so routine review comments don’t need you.
Plan gate	On (keep)	Adversarial plan review before each session executes — see below. This is the seeded default; keep it.
Epic mode	Auto	On the Epic panel, “auto” drains without asking. “Attended” waits for Approve next on every spawn.

Repos without CI. In a GitHub repo where no workflow in .github/workflows runs on pull requests (none at all, or only scheduled or manual ones), nothing checks a PR. So the merge train and epic auto-land hold those PRs instead of merging them. The session banner says no CI and the epic row shows Auto-land held: no CI. To lift the hold, add a CI workflow, merge yourself, or turn on Merge without CI in the automation pane (see Auto-merge without PR CI). Child PRs still merge into the epic branch, so a project can grow its own CI before anything reaches main.

The Epic panel’s Apply hands-off defaults button sets Autopilot, Full-auto merge (Draft off), Critic, and Auto-Address in one click, and switches the epic to auto mode. It deliberately does not touch Plan gate (see the next section).

Plan gate is hands-off-safe — keep it on

It’s a common misconception that Plan gate forces you to approve every session’s plan by hand. That is only true for a session meant to be driven by hand — interactive, with Autopilot off. A session that is meant to run hands-free releases itself: either because it is drain-spawned (every epic child is) or because Autopilot is on, which is why an interactive task with Autopilot on also needs no Go. The one exception is a Codex session sharing its working directory — Autopilot requires an isolated worktree, so that session waits for your Go regardless. For an epic:

• When the adversarial plan reviewer approves a plan, the session is released straight into execution — no operator approval needed.
• When the reviewer requests changes, the findings are steered back into the planning agent automatically and it revises, for up to 5 rounds.
• Only if a plan still can’t be approved after 5 rounds does the epic hand back to you — a genuine “this plan can’t converge” signal that should stop it.

So Plan gate gives you an adversarial plan review on every session for free, without blocking a hands-off drain. Keep it on. If you want to skip plan review entirely, you can turn it off in the automation pane — you’ll trade away that pre-execution check; Critic (code review of every push) still runs regardless.

Sign-off authority — leave it on “human”

You don’t need to change Sign-off by. The sign-off gate only applies in Draft mode, and the hands-off recommendation runs with Draft mode off (Full-auto merge on). With Draft off, the sign-off authority is inert, so leaving it at the default “human” is safe and does not hold anything up.

What still stops a hands-off epic

Hands-off does not mean unattended-and-unsafe. Most pauses are transient — the epic keeps in-flight work running and resumes on its own — and only a few are terminal holds that need you.

Transient (self-resolving, no action needed):

• A critic REWORK you have Auto-Address for. A blocking critic verdict pauses spawning new sibling sessions while the in-flight session keeps auto-addressing the findings. It resolves and the epic continues on its own — unless the agent can’t clear it within the auto-address round cap (then it becomes a terminal hold, below).
• A plan under adversarial review. The plan reviewer iterates with the planning agent (up to 5 rounds) before anything executes.
• Usage ceiling. New spawns pause when 5-hour / weekly usage reaches the repo’s ceiling (default 80%), then resume as usage drops. To keep going anyway, lift the ceiling for this run — Ignore usage ceiling in the epic’s run control, or Ignore for epic #N next to the pause banner. It lasts until the run is paused or stopped; the credit ceiling still applies.
• Concurrency cap. Only N auto-sessions run at once (default 1); the rest queue.
• Epic branch behind main. Shepherd rebases the epic’s integration branch onto main about once an hour, whenever no child is running or in review. If it has been behind for 4 hours without such a gap, the epic stops starting new children (“Basis veraltet”), lets the running ones finish, rebases, and continues. Continue anyway in the run control lifts the pause until main moves again.
• Previous epic still landing. An epic that hasn’t started any child yet waits while another epic’s landing PR in the same repo is open, so its branch is cut from a main that already has that work. Continue anyway starts it regardless.

Terminal (needs you):

• A stuck session that can’t make progress.
• A REWORK the agent can’t auto-resolve within the auto-address round cap.
• A plan the adversarial reviewer can’t get approved within 5 rounds.
• A critic error — Shepherd won’t advance on an uncertain review.
• The credit ceiling — Shepherd never keeps spending pay-as-you-go credit unattended.
• A setting that forbids unattended starts — the repo’s sandbox is Standard (interactive only), the epic runs Codex under anything but Trusted, Autonomous lacks bubblewrap or its egress backend on this host, or a ticket’s target repo has Auto-Drain off. The run shows Halted with the cause; change the setting (or install the backend) and the next child starts. For the sandbox, CLI and host causes the epic’s run area lists every cause (repo, epic or host) and offers only the fixes that really start the ready children — Apply changes the repo’s sandbox and, if needed, the epic’s CLI in one step, and Undo puts both back. The epic’s row in the backlog list shows the same halt with Fix, which opens that choice right beside the row (a sheet on the phone), and the Automation tab counts the halts in the repo’s settings or on this host. With nothing selected, the repo overview names a halt in the repo’s settings or on this host once, at the top: Switch to Autonomous appears when that alone lifts it here, and Other choice … opens the same choice. Each epic card keeps only its own cause with its fix (e.g. CLI to Claude Code), and queued or not-started epics show their pre-check — what would hold them on start — without starting.
• Epic branch conflicts with main — the rebase above hits a real conflict. No new child starts; an agent rebases the branch and resolves it — even with Auto-Drain off — and a second one retries if the first leaves it conflicting. If that doesn’t clear it you get a notification: press Resolve conflict to start another agent, or Continue anyway to keep the epic going on the old base until main moves again.
• Epic base-branch divergence — a child PR retargeted off the epic integration branch; the epic is blocked until it’s pointed back at the integration branch.
• A stack that lost a middle layer, if you run with stacked epic children on — the layers above it can’t land until you abandon or merge them.

You don’t have to open the epic to act on a hold. While the drain holds the leading epic for an unfinished project bootstrap, the usage ceiling, its integration branch, a stuck agent or an attended approval, the epic’s row in the backlog list shows the hold with its scope (REPO, RUN or EPIC) and the action that already exists for it: View bootstrap and Override hold, Lift for this run, Get the conflict resolved and Continue anyway, Open session, or Approve (amber — it waits for you rather than stopping). The repo overview shows the same: a bootstrap hold once at the top, since it holds every epic, and the others at the leading epic’s card.

Starting the epic

1. Make sure the epic exists (a parent issue with sub-issues or an epic-dag body) — see Authoring an epic to create one, and Concepts & glossary for the epic model.
2. Open the epic’s panel from its issue row.
3. If it’s your first epic, the Run this epic hands-off panel offers Apply hands-off defaults — or set the pane manually per the table above.
4. Confirm the epic is in auto mode and press Start.

Shepherd spawns the first ready child immediately, then drains the rest as their dependencies complete, landing one aggregate PR at the end.

Queueing the next epic

One epic leads per repo. To line up more, press Queue on another epic while one leads. The queued epics are listed under Warteschlange in the repo’s run area — drag them by the grip, or use the ↑/↓ buttons, to change the order. The head of the queue starts on its own, with its own settings, as soon as the leader has all children merged into its integration branch — or when you Stop the leader. Its first child waits until the leader’s landing PR is merged (see Previous epic still landing above). Pausing the leader keeps the queue waiting; starting a different epic puts that one in front of the queue.

A landing-PR repair session (CI repair or conflict rework) does not take one of the repo’s agent slots.

Incremental landing

By default an epic lands through its integration branch: children merge into epic/<#>-<slug>, and one landing PR ships the whole epic to main at once. For an epic whose children can each ship on their own, switch Landing to Incremental in the epic’s run area, or pick it when you approve an epic draft.

In incremental mode:

• Each child bases on main and opens its PR against main. There is no integration branch and no landing PR.
• A child PR merges like any other PR in the repo. The merge train lands it when the session is full-auto. Otherwise it waits for you to merge it.
• If the epic has dependencies but the repo doesn’t have both autopilot and auto-merge on, nothing merges child PRs, so each dependent child starts only after you merge its blocker. The run area and the draft’s landing choice warn about this. While the epic runs, the run area names the green PR that waits for your merge and the children it blocks.
• A child PR that touches database migrations is never merged by the merge train. It is held as migrations, and you merge it by hand.
• Shepherd closes the parent issue when the last child is done.
• main holds a partly shipped epic until the last child lands. Don’t use this mode for an epic that ships one feature in slices.
• With stacked epic children on, a dependent child starts on its predecessor’s open PR, and the stack is rooted at main. The merge train lands it one layer at a time, bottom first.

You can change Landing only before the epic first runs. After that it is locked.

How long will this epic take?

Hover an epic’s EPIC badge in the Herd to see how long it has run and when it is forecast to land. The epic’s detail in Repos adds time tiles, a timeline of every step and a Duration column in its step list: how long a merged step took, a running step’s clock, and when a waiting step is planned to run (its estimate instead while the epic is paused). Both read the same epic clock and forecast.

The epic clock

The epic clock measures how long the epic has run — not how long ago it started.

• It starts the first time the epic runs — usually when you press Start.
• It runs only while the epic is running. Pause stops it, and paused time never counts.
• Only one epic leads per repo at a time. When another epic supersedes it, the epic shows as stopped: its clock stands, but it is not reset. When that epic runs again, the clock carries on from where it stood, and the gap counts like a pause.
• It stops when the last step is in and the landing begins — the epic’s PR into main, its CI and the merge. The landing is timed on its own.

Once the epic has landed, its Total runs from the first start to the landing’s merge, minus the pauses.

Agent time and waiting time

The clock is wall time. Two more figures show what happened during it:

• Agent time is the summed run time of every agent session that worked on the epic’s steps. Parallel agents each count in full, so it can exceed the clock.
• Waited, no agent ran is the time the clock ran while no agent worked on any step — for example between one step merging and the next one starting, or while the next spawn waited on the usage ceiling or on an agent slot held by a task outside the epic.

Paused time never counts as waiting: the clock stood still. Pause leaves running sessions intact, though, so an agent that keeps working while the epic is paused still adds to agent time.

How the forecast is built

The forecast plays the rest of the epic through in three parts:

1. A duration per step. Shepherd blends two sources: a repo median, counted as two samples, and every step this epic has already finished, measured from its first session until it merged into the epic’s integration branch. The repo median is taken over the steps of the repo’s other epics that finished in the last 30 days, measured the same way. With fewer than three of those, or for an incremental epic, whose steps merge into main like any task, it falls back to the repo’s median lead time over the last 30 days. The estimate is the mean, so the epic’s own pace takes over as its steps finish. A running step is given what is left of the estimate, but never less than a tenth of it; a step running past 1.5× the estimate is flagged as taking much longer than usual.
2. The order. The open steps are laid out in epic order over the repo’s agent slots — the Cap in the automation pane, the concurrency cap above. A step starts once the steps it depends on are done and a slot is free, so with one slot the steps run one after another. The forecast assumes the epic has the slots to itself: an auto-started task outside the epic that takes a slot pushes the real finish later.
3. The landing. After the last step comes the landing, priced at the median of the repo’s past epic landings, or 20 minutes when the repo has never landed one. Once the landing is underway, only its remainder is left.

While the epic is paused or stopped there is no finish time; the forecast shows Remaining from resume instead. With no repo median and no finished step yet, there is no forecast at all.

Range and confidence

The range plays the same schedule through twice more, with a short and a long step. Each is the further out of two values: the 25th or 75th percentile of the blended step durations, and the blend taken with the repo’s 25th or 75th percentile in place of its median — so a repo whose steps vary a lot gets a wide range from the start. Until three of the epic’s own steps are measured, the two are pushed out to at least 25 % below and 35 % above the estimate. The range narrows with every finished step.

Confidence says how much of the forecast rests on this epic’s own steps. The first row that fits applies:

Confidence	When
high	At least half of the epic’s steps have merged, or four or more are measured.
medium	Two or three steps measured.
low	One step measured.
very low	None measured yet — the forecast rests on the repo median alone, and says so (“repo median only”).

Why the first estimate is wide

Before the first step merges, the forecast knows nothing about this epic. Every step is priced at the repo median — a median over other epics’ steps (or over tasks of every size), not over this epic’s — the range is widened, and confidence is very low. Read it as a rough guide. Each finished step replaces part of that guess with the epic’s own pace, and the range narrows.

The first forecast after the first merge is kept as the first estimate. If a later forecast lands 15 minutes or more past it, the hover shows the slip (“so far ~…”) and, when one step is taking much longer than usual, names it.

The “faster with N slots” hint

When a step is ready but waits for a free agent slot, the epic’s detail in Repos can offer With N agent slots done around ~… instead of ~…. It appears only when every slot is taken by an auto-started session and one more slot would land the epic at least 15 minutes sooner. Its Allow N slots button opens the Automation tab with the Cap focused; it never changes the cap itself.

Raising the cap costs:

• One more agent at a time. That is the point — and it means more spend at once.
• It is repo-wide. The cap counts every auto-started session in the repo, not only this epic’s, so every auto-started task there gets the extra slot.
• Usage drains faster. More agents at once reach the usage ceiling sooner, and new spawns pause there until usage drops.

Manual steps from child PRs

Child PRs merge into the epic branch, not main, so the manual steps they declare (a shepherd:manual-steps block) are carried forward. The landing PR body lists them all in one shepherd:manual-steps block:

• Deduplicated. A step declared by several children appears once, with each origin: (from #12, #15).
• Done stays done. A step ticked in its child PR, in that child’s Owed card, or in the landing PR body itself is listed as - [x]. A body refresh keeps those ticks.

When the landing PR merges (from Shepherd, or directly on GitHub once the closed parent clears the epic), its open steps become one Owed card for the epic (EPIC-<n>), with done steps already ticked. The child Owed cards those steps cover are cleared, so nothing is listed twice.

When the landing PR’s CI is red

A red landing PR is not your turn straight away. The epic’s card on the Epics to land band shows the red checks (each with its log), and a Who’s handling it bar with the steps Shepherd still takes before it hands over:

1. Checks re-run — Shepherd re-runs the failed jobs up to 2 times per head commit, since a red check is often a flake. This runs while Full-auto merge, Auto-Drain or an epic run is active, on GitHub only, and never in Draft mode.
2. Agent repair — if CI is still red, Shepherd starts one repair agent. It fixes the cause (or the PR’s metadata, e.g. a too-long title) and pushes straight to the integration branch — no new PR. This step runs only with Auto-Drain on; with it off, the card says it was skipped and links to the repo automation.
3. You — only once nothing automatic is left does the card say your turn.

Fix CI failures on the card starts a repair agent yourself at any time — it bypasses Auto-Drain and the one-repair limit, and is refused only while a repair agent is already working. After a repair that did not help, the card offers Try again and a link to the last repair session. A landing PR that conflicts with main has the counterpart, Resolve conflicts.