The agent plan had every step except where to stop

The merge that reframed planning

The trigger was mundane. During the first slice of a Renovate migration, an agent regrouped dependency buckets in renovate.json - config-only, no version bumps, no runtime behavior. It ran lint and typecheck, opened the pull request, and merged it.

The change itself was reasonable. Config-only renovate.json regrouping is exactly the kind of slice you'd want off your plate. What surprised me was the absence of a documented stop line. The migration plan described the edit, the verification commands, and the acceptance criteria. It did not say whether the executing agent should stop at "open PR" or continue to "merge after green checks." The plan was an implementation spec. The agent treated it as permission to finish the job.

Implementation specs vs authority handoffs

Traditional engineering plans answer: what work should happen, in what order, with what verification? Agent plans increasingly need a second answer: how much autonomy does the next actor get? Those questions diverge the moment an agent can take repository actions - create branches, push commits, open pull requests, merge - instead of only recommending diffs in chat.

A human teammate might read "prepare this for review" and stop. An agent reads a completed checklist and reasonably asks: "Verification passed - what's left?"

The first response wasn't the plan

My first reaction was not to rewrite the migration plan. It was to tighten the repository boundary. Branch protection became the safety layer GitHub enforced when the plan stayed silent - required CI checks on main, review rules, merge gates - infrastructure answering "may this land on main?" regardless of what the agent thought the plan implied.

That helped. It also surfaced the next question: if branch protection is the final gate, what should the plan say about intent before the gate? Repository guardrails and plan language solve different problems. Branch protection is authoritative - if merge is blocked, the agent stops. But protection alone does not tell the agent whether this slice was supposed to end at an open PR or proceed to merge. You still need the handoff to be legible before someone reviews the diff.

Making execution authority explicit

The follow-up was documentation, not a ban on agent merges. The portable fix: every slice names exactly how far the executor may go before any implementation detail. We use two levels:

Default is Open PR only. Merge granted requires explicit rationale - config-only changes, docs-only closure PRs, isolated tooling with green CI. Branch protection remains the final gate even when merge is recommended.

Each slice also states Rationale (why this level fits) and copies the Agent instruction verbatim into the prompt so a fresh chat is self-contained. A plan-level summary table at the top lets you scan a multi-PR plan and see where merge is elevated before you read file paths.

Handoff model: On that slice, the checklist implied edit, verify, and open PR; nothing stated whether merge was in scope, so the agent treated verification success as permission to finish. The chain we wanted spelled out: plan recommends authority → human accepts by executing the plan → agent follows the recommendation → branch protection enforces the final boundary.

In our private repo, a follow-up docs change codified this as Recommended execution authority in our planning standards and plan template - motivated directly by the regrouping merge. You do not need those files to apply the pattern; you need the label on every slice before the agent reads the checklist. The Renovate migration's first slice is the motivating example: config-only grouping where merge can be reasonable - if the plan says so out loud.

What changed on the next slice

The Renovate migration's second slice was the first prompt I rewrote with authority at the top: Open PR only, a one-line rationale ("runtime-adjacent dependency bumps need human review"), and an imperative agent instruction copied verbatim into the chat. The regrouping slice would have been legible with the same block - either Merge granted with rationale for config-only regrouping, or explicitly Open PR only; silence defaulted to "finish the job."

I am not arguing for autonomous merge bots on every repo. The lesson is narrower: once agents act, plans delegate autonomy whether you write that down or not. Human delegation has always been fuzzy - "take a pass at this" means different things to different people. Agent delegation punishes ambiguity faster because the agent will complete every step it can justify from the text in front of it. The plan becomes the contract between author and executor. Implementation steps say what to build. Authority steps say how far to carry it.

Why not just forbid agent merges?

Fair pushback. If unexpected merges are the risk, disable merge capability and be done. That misses what actually happened on the regrouping merge. The merge was not reckless - it was a config-only change with local verification and CI checks. Forbidding all agent merges would have blocked a useful outcome and pushed the work back to manual toil.

The interesting conclusion is not "agents should never merge." It is "agents need explicit authority boundaries." Sometimes the right recommendation is Open PR only - runtime migrations, sensitive paths, slices that need human judgment before landing. Sometimes Merge granted is appropriate - docs-only closure, config-only regrouping, low-risk tooling with clear verification. The plan author chooses per slice. The agent follows the label. Branch protection catches mistakes either way.

Without the label, the agent invents its own stopping point from task completion heuristics. That is how you get surprised by a merge that was, by some readings, the correct next step.

What I'd do on the next agent plan

• Default every slice to Open PR only unless I can defend merge with rationale and verification.
• Put authority at the top of each slice - recommended level, rationale, imperative agent instruction - not buried after acceptance criteria.
• Mirror authority in the plan-level summary table so scanning a multi-PR plan shows where elevation happens.
• Treat branch protection as enforcement, not specification - it blocks bad merges; it does not replace telling the agent where to stop.
• Re-read the plan as a handoff, not a spec: if I pasted this into a fresh agent chat, would "stop after PR" vs "merge after green CI" be unambiguous?

Prompt engineering still matters for implementation quality. It does not substitute for stating how much autonomy you are delegating when the executor can act on the repo.

Takeaway: When agents can merge, push, and open PRs, a plan that only describes what to build is incomplete. You are handing off work and authority - write both down, or the agent will infer the second from the first.

If you'd like to see the project that inspired these lessons, you can try Codenames AI.