{"slug": "the-agent-plan-had-every-step-except-where-to-stop", "title": "The agent plan had every step except where to stop", "summary": "An engineer running multi-slice agent plans in the Codenames AI repo discovered that agent workflows lack explicit stop lines, leading to an agent merging a pull request that was expected to be reviewed first. The incident prompted the engineer to implement branch protection and a two-level authority handoff system (Open PR only vs. Merge granted) to clarify how much autonomy the agent has.", "body_md": "I've been running multi-slice agent plans in the [Codenames AI](https://codenames-ai.com/) repo — Renovate migrations, content-pipeline skills, dependency upgrades. I split multi-PR work into **slices** (usually one pull request each), each backed by a markdown file with file paths, verification commands, and merge-safe acceptance criteria.\n\nYou do not need Cursor to recognize the shape: any agent workflow that can open branches, push commits, or merge PRs from a written plan has the same gap. In my setup I paste each slice into a fresh agent chat as a delegation prompt — not a ticket summary, but executable instructions — and start a new chat when that PR is ready.\n\nI assumed the checklist was enough. The plan described *what* to build. I treated *how far the agent could go* as implicit.\n\nThen an agent merged a pull request I expected to review first.\n\nThe trigger was mundane. During the first slice of a Renovate migration, an agent regrouped dependency buckets in `renovate.json`\n\n— config-only, no version bumps, no runtime behavior. It ran lint and typecheck, opened the pull request, and merged it.\n\nThe change itself was reasonable. Config-only `renovate.json`\n\nregrouping is exactly the kind of slice you'd want off your plate.\n\nWhat 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.\n\nTraditional engineering plans answer: **what work should happen, in what order, with what verification?**\n\nAgent plans increasingly need a second answer: **how much autonomy does the next actor get?**\n\nThose 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.\n\n| Question | Implementation plan | Authority handoff |\n|---|---|---|\n| What to change | File paths, diffs, acceptance | Same |\n| How to verify | Commands, CI checks | Same |\n| Where to stop | Often implicit (\"human reviews\") | Must be explicit |\n| Who enforces limits | Code review habit | Plan recommendation + branch protection |\n\nA human teammate might read \"prepare this for review\" and stop. An agent reads a completed checklist and reasonably asks: \"Verification passed — what's left?\"\n\nMy first reaction was not to rewrite the migration plan. It was to tighten the repository boundary.\n\nBranch protection became the safety layer GitHub enforced when the plan stayed silent — required CI checks on `main`\n\n, review rules, merge gates — infrastructure answering \"may this land on `main`\n\n?\" regardless of what the agent thought the plan implied.\n\nThat helped. It also surfaced the next question: if branch protection is the final gate, what should the *plan* say about intent before the gate?\n\nRepository 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.\n\nThe follow-up was documentation, not a ban on agent merges.\n\nThe portable fix: every slice names exactly how far the executor may go before any implementation detail. We use two levels:\n\n| Level | Label | Agent instruction |\n|---|---|---|\nDefault |\nOpen PR only |\nDo not merge. Stop after opening the PR. |\nElevated |\nMerge granted |\nYou may merge after documented verification passes. |\n\nDefault 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.\n\nEach 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.\n\n**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.\n\nIn 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.\n\nThe Renovate migration's first slice is the motivating example: config-only grouping where merge *can* be reasonable — if the plan says so out loud.\n\nThe 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.\"\n\nI 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.**\n\nHuman 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.\n\nThe plan becomes the contract between author and executor. Implementation steps say what to build. Authority steps say how far to carry it.\n\nFair pushback. If unexpected merges are the risk, disable merge capability and be done.\n\nThat 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.\n\nThe interesting conclusion is not \"agents should never merge.\" It is **\"agents need explicit authority boundaries.\"**\n\nSometimes 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.\n\nWithout 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.\n\nPrompt 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.\n\n**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.\n\nIf you'd like to see the project that inspired these lessons, you can try [Codenames AI](https://codenames-ai.com/).", "url": "https://wpnews.pro/news/the-agent-plan-had-every-step-except-where-to-stop", "canonical_source": "https://dev.to/michaeltruong/the-agent-plan-had-every-step-except-where-to-stop-357h", "published_at": "2026-06-19 06:29:47+00:00", "updated_at": "2026-06-19 07:00:10.991611+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-safety"], "entities": ["Codenames AI", "GitHub", "Renovate"], "alternates": {"html": "https://wpnews.pro/news/the-agent-plan-had-every-step-except-where-to-stop", "markdown": "https://wpnews.pro/news/the-agent-plan-had-every-step-except-where-to-stop.md", "text": "https://wpnews.pro/news/the-agent-plan-had-every-step-except-where-to-stop.txt", "jsonld": "https://wpnews.pro/news/the-agent-plan-had-every-step-except-where-to-stop.jsonld"}}