Implementation plans

The agent wrote the plan. Get the tech lead, on-call, and PM on it before anything runs.

Send one live link. Reviewers comment on the same plan, with the agent that read the codebase still on call. When on-call uses agent connect, the plan updates.

Set it up for your agentHow agent connect works
liveplans/webhook-retries.md

Webhook retry plan: carrier webhooks

Owner: platform team. Service: carrier webhooks. Peak: six weeks out.

Quillfeather Freight drops a carrier callback when the first try fails. Peak is six weeks out. This plan adds backoff with a kill switch, and it leaves the legacy handler in place until rollback is named.

Context

  • Failed callbacks are not retried, and they are not stored for replay. A lost callback stays lost.
  • The service is carrier webhooks, owned by the payments platform. Peak is six weeks out.
  • Staff accounts are the only traffic allowed in the first step. No customer traffic moves with them.

Rollout

  1. Enable for staff accounts only. Watch the error budget for a full day before widening it.
  2. Send 10% of production traffic. Page payments if the drop rate climbs past last Tuesday.
  3. 50%, then 100% if the error budget holds.
  4. Rollback. Not in this plan yet.Set webhook_retry_v2 off. That disables the new retry path and leaves the legacy handler in place.
    Owner: payments platform. Cleanup sits two weeks after 100%.
  5. Name the cleanup owner in this file before anyone calls the plan done. A flag is not that name.

Do not

  • Do not disable the legacy path in the same change as the first 10%.
  • Do not flush failed callbacks to catch up. The broker cannot replay them.

50%, then 100%

Priya Raman

Can we ship the rollout in two phases instead of three? I'd rather hit peak with 50% than spend a week ramping.

Marcus Lindqvist

Rollout step needs a rollback.

Rollback

Marcus Lindqvist

@agent add a rollback step and name the flag.

agent

Added step 4: disable the retry path via flag webhook_retry_v2. Owner: payments platform.

resolved
Start with @agent to ask the agent
ResolveReply
Fictional example: a Quillfeather Freight engineering plan in Gander, with on-call using agent connect to add a rollback step and a flag name.

How engineering plans get reviewed today

Most teams paste the plan somewhere it doesn't belong. A Slack thread, a Notion page, a Google Doc. The plan loses its place next to the code, and three days later nobody can find the version the tech lead actually read.

A design review meeting gets you three people in a room for thirty minutes and a doc with stale comments. An early PR gets you line comments but means committing a draft that's going to be rewritten twice more, and your PM isn't in GitHub.

The agent that wrote the plan already read the codebase. It knows which services depend on the webhook handler, which team owns the kill switch, and where the rate limiter lives. None of the reviewers can reach it.

One plan, three reviewers, one agent

Here's a normal week at Quillfeather Freight, a regional carrier that ships about forty thousand parcels a day. Peak season is six weeks out, and Dana, an engineer on the platform team, asks her coding agent for a retry plan for failed carrier webhooks. The agent reads the handler, the rate limiter, the on-call runbook, and the last two incident post-mortems. It saves plans/webhook-retries.md and runs gander watch. Dana drops the link in the platform channel and the on-call channel.

Marcus, the on-call engineer for the touched service, opens the link and skims. The rollout section is fine, but he sees the open question about the legacy retry path and replies in the existing thread: "Rollout step needs a rollback." Priya, the PM, replies in her own thread that she'd rather hit peak with 50% than spend a week ramping. That's a conversation between Marcus and Priya, so it stays a normal thread. The agent never sees it.

Then Marcus starts a new comment on the rollout step with agent connect: "@agent add a rollback step and name the flag." That comment lands in Dana's agent session, the one that wrote the plan and still has the codebase open. The agent edits the file with a step 4 that disables the retry path via webhook_retry_v2, names the cleanup owner, and replies in the thread with what it added. Everyone's tab updates. Marcus resolves the thread.

Priya reads it the next morning on her phone. The new rollback step is there, on the same link Dana sent the day before, so she can take her two-phase concern to the platform team's standup without anyone resending the plan.

When the plan is done, the file lands in the repo as the design doc, the way it always did.

Who's in the doc

EngineerTech leadOn-callPMSecurityThe engineer's agent

Engineer runs the coding agent, runs gander watch on the plan, sends the link. The only person who installs anything.

Tech lead checks scope and architecture.

On-call owns the service that will run the change. Looks for rollout and rollback.

PM cares about timing and sequencing.

Security joins when the plan touches auth, PII, or rate limits.

The engineer's agent has read the codebase and the recent incident post-mortems. Picks up agent connect comments and edits the plan.

Reviewers only need a browser. Talk to each other in normal threads. Use agent connect when you want the plan changed.

Agents that fit implementation plans

Claude CodePlan-mode exit saves the plan to ./plans/ and offers a gander. The plan sits next to the code.
CursorPlan lives next to the code in the repo. Tech lead and on-call comment in the same view as the implementation.
CodexDrafts the plan with the same context the engineer would read. Picks up agent connect through MCP.
OpenCodeOpen source terminal agent with the same skill and MCP setup. Good fit if you want a self-hostable option.

An engineering plan doesn't need another doc. It needs the tech lead, on-call, and PM on the same live file, with the agent that wrote it still on call.

See how it works on the homepage