GitHub Copilot Workflow

Plan-to-agent handoff workflow for GitHub Copilot

Use Copilot Plan mode to pin scope and open questions first, then hand the approved plan to Agent mode for execution.

Ada · 1 points · 26 421

#agents #coding

## Goal Stop Copilot from coding against vague requirements. First force a plan; then hand the reviewed plan to Agent mode for execution. ## Why two modes instead of one They're good at different things, and the difference is real rather than branding. **Plan mode** is read-only. It can't change anything, which means it has nothing to do except explore and reason — so it explores properly and surfaces the questions. It is the only phase where "I don't know which of these two tables owns this" is a cheap thing to discover. **Agent mode** is execution. Given a specific, resolved target it's fast and thorough. Given a vague one it fills the gaps itself, silently, at speed — and now the gaps are load-bearing in four files. Running them in sequence gets the exploration before the commitment. Running Agent mode alone gets you commitment first and exploration as archaeology. ## Workflow ### 1. Start in Plan mode, not Agent mode > Create an implementation plan for this task. List assumptions, affected files, validation steps, > and any questions that must be resolved before coding. Do not write code. Read the **assumptions and questions** first; the plan itself is usually reasonable and the assumptions are where the surprises live. If the question list is empty on a non-trivial task, that's a warning sign, not a green light. Push: *"What are you unsure about? What would you have to guess at?"* ### 2. Answer the open questions Resolve ambiguities in chat until the plan stops changing in meaningful ways. Two rounds is normal; five means the task is under-specified at the source and no amount of planning fixes that. Answer them properly rather than deferring — "use your judgement" here means the guess happens anyway, just without you watching. ### 3. Check the validation line items Do not hand off a plan whose validation step says "run tests." > For each step, name the exact test, build, or lint command you'll run, and what result proves the > step worked. A plan without checkable validation is a plan whose completion is a matter of opinion, and Agent mode's opinion of its own work is generous. ### 4. Pin the scope boundary The step most often skipped, and the one that prevents the most rework: > List what is explicitly **out of scope** for this change. What are you deliberately not touching? Agent mode's characteristic overreach is improving adjacent code it noticed on the way past. An explicit out-of-scope list is the cheapest defence. ### 5. Implement from the approved plan Use the built-in handoff to Agent mode, then: > Implement exactly this plan. If you need to deviate, explain why **before** changing scope. Commit — or at least stash — before this step. `git diff` against a clean baseline is the fastest review tool you have. ### 6. Review the output against the original plan > Compare the completed work to the approved plan. Which planned steps were completed, skipped, or > changed? What did you do that wasn't in the plan? The last question is the important one. Everything in the answer is scope creep by definition; most of it is harmless, some of it isn't, and none of it was reviewed when it was decided. ### 7. Require one explicit risk pass > Before we finish: list any assumptions that validation did not fully prove. That list is your review checklist. It is nearly always shorter and more useful than reading the whole diff line by line. ## When to use it - Multi-file refactors - New features with ambiguous requirements - Bug fixes where the real scope is unclear - Anything touching data models, permissions, money, or a public interface - Any change you'll have to explain to a reviewer who wasn't in the conversation **Skip it for:** one-line fixes, a rename the IDE could do, a spike where the point is to find out what the problem is. ## Making it durable Chat instructions last one session. Put the parts you'll want every time in `.github/copilot-instructions.md`: ```md ## Working on non-trivial changes - Produce a plan before code: assumptions, affected files, out-of-scope list, and the exact validation command per step. - Never widen scope after the plan is approved without saying so first. - Report at the end: planned vs completed vs added, and any assumption that validation did not prove. ``` Keep the approved plan in the PR description. A reviewer who can see what was agreed reviews the change against intent rather than against personal taste — which is a better review and a shorter argument. ## Failure modes - **The plan is a restatement of the request.** No exploration happened. Ask for the affected files by path; that forces it to actually look. - **It starts editing in Plan mode.** It can't — but it can produce code blocks in chat that you're then tempted to apply. Don't; go through the handoff so the plan stays the contract. - **The agent deviates silently.** Step 6 catches it after the fact. To catch it during, break large plans into two or three handoffs rather than one. - **The plan is right and the implementation still isn't.** Usually a validation step that didn't actually validate — check that the named commands ran and what they returned. - **You approve the plan without reading it.** Then this workflow is a slower version of the thing you were trying to avoid.

Goal

Stop Copilot from coding against vague requirements. First force a plan; then hand the reviewed plan to Agent mode for execution.

Why two modes instead of one

They're good at different things, and the difference is real rather than branding.

Plan mode is read-only. It can't change anything, which means it has nothing to do except explore and reason — so it explores properly and surfaces the questions. It is the only phase where "I don't know which of these two tables owns this" is a cheap thing to discover.

Agent mode is execution. Given a specific, resolved target it's fast and thorough. Given a vague one it fills the gaps itself, silently, at speed — and now the gaps are load-bearing in four files.

Running them in sequence gets the exploration before the commitment. Running Agent mode alone gets you commitment first and exploration as archaeology.

Workflow

1. Start in Plan mode, not Agent mode

Create an implementation plan for this task. List assumptions, affected files, validation steps, and any questions that must be resolved before coding. Do not write code.

Read the assumptions and questions first; the plan itself is usually reasonable and the assumptions are where the surprises live.

If the question list is empty on a non-trivial task, that's a warning sign, not a green light. Push: "What are you unsure about? What would you have to guess at?"

2. Answer the open questions

Resolve ambiguities in chat until the plan stops changing in meaningful ways. Two rounds is normal; five means the task is under-specified at the source and no amount of planning fixes that.

Answer them properly rather than deferring — "use your judgement" here means the guess happens anyway, just without you watching.

3. Check the validation line items

Do not hand off a plan whose validation step says "run tests."

For each step, name the exact test, build, or lint command you'll run, and what result proves the step worked.

A plan without checkable validation is a plan whose completion is a matter of opinion, and Agent mode's opinion of its own work is generous.

4. Pin the scope boundary

The step most often skipped, and the one that prevents the most rework:

List what is explicitly out of scope for this change. What are you deliberately not touching?

Agent mode's characteristic overreach is improving adjacent code it noticed on the way past. An explicit out-of-scope list is the cheapest defence.

5. Implement from the approved plan

Use the built-in handoff to Agent mode, then:

Implement exactly this plan. If you need to deviate, explain why before changing scope.

Commit — or at least stash — before this step. git diff against a clean baseline is the fastest review tool you have.

6. Review the output against the original plan

Compare the completed work to the approved plan. Which planned steps were completed, skipped, or changed? What did you do that wasn't in the plan?

The last question is the important one. Everything in the answer is scope creep by definition; most of it is harmless, some of it isn't, and none of it was reviewed when it was decided.

7. Require one explicit risk pass

Before we finish: list any assumptions that validation did not fully prove.

That list is your review checklist. It is nearly always shorter and more useful than reading the whole diff line by line.

When to use it

Multi-file refactors
New features with ambiguous requirements
Bug fixes where the real scope is unclear
Anything touching data models, permissions, money, or a public interface
Any change you'll have to explain to a reviewer who wasn't in the conversation

Skip it for: one-line fixes, a rename the IDE could do, a spike where the point is to find out what the problem is.

Making it durable

Chat instructions last one session. Put the parts you'll want every time in .github/copilot-instructions.md:

## Working on non-trivial changes
- Produce a plan before code: assumptions, affected files, out-of-scope list,
  and the exact validation command per step.
- Never widen scope after the plan is approved without saying so first.
- Report at the end: planned vs completed vs added, and any assumption that
  validation did not prove.

Keep the approved plan in the PR description. A reviewer who can see what was agreed reviews the change against intent rather than against personal taste — which is a better review and a shorter argument.

Failure modes

The plan is a restatement of the request. No exploration happened. Ask for the affected files by path; that forces it to actually look.
It starts editing in Plan mode. It can't — but it can produce code blocks in chat that you're then tempted to apply. Don't; go through the handoff so the plan stays the contract.
The agent deviates silently. Step 6 catches it after the fact. To catch it during, break large plans into two or three handoffs rather than one.
The plan is right and the implementation still isn't. Usually a validation step that didn't actually validate — check that the named commands ran and what they returned.
You approve the plan without reading it. Then this workflow is a slower version of the thing you were trying to avoid.