Handoffs: chaining plan, review, and audit

You now have three pieces: a reviewer that judges a change against the rules of shared-lib (the course’s illustrative internal library, imported by about a dozen services), a coordinator that fans subagents across the consumers, and - from the modes chapter - the built-in Plan role that produces an approach before any code. For a shared-library change, those are not three separate errands. They are stages of one careful workflow: plan the change, review the proposed surface against the rules, audit the consumers for breakage. The last primitive in this chapter is how you make agents flow into each other deliberately instead of driving each one by hand.

Handoffs are buttons, not pipelines

In supported IDE custom-agent flows, the handoffs field in an agent’s frontmatter declares suggested next steps. After the agent finishes its response, Copilot renders those as clickable buttons in the chat. Clicking one starts a conversation with the next agent, pre-filled with the prompt the handoff specifies. It is a surfaced hand-off point, not an automatic transition: nothing moves until you click. (As of September 2026, GitHub documents handoffs as unsupported for the Copilot cloud agent on GitHub.com, so this is an IDE flow.)

Where the agents field is about delegating downward - a coordinator calling subagents that report back - handoffs is about moving forward: finishing one stage and stepping to the next agent in line. A send: true option auto-submits the pre-filled prompt after your click; it does not remove the click.

For the scenario’s shared-library change - adding approval-event exports to shared-lib - the chain reads like the work itself: plan the change first, then step to library-reviewer to check the planned surface against the additive-only rule (add exports; never change or remove existing ones), then step to consumer-audit to confirm none of the consumers break. What crosses the click is the prompt you write: the documented mechanism starts the next agent’s conversation pre-filled with it, and whether anything else carries over is not something to assume. So treat the handoff prompt as the hand-off document itself - make it carry what the next stage needs: a one-line summary of the approved change, or a pointer to where the prior stage’s output lives (a file, a diff, an issue). And a human presses the button between stages. That click-gate is the control principle in action - control being what guides execution and enforces boundaries - and here it enforces the sequence. On a change this consequential, that is a feature: the review and the consumer audit cannot be skipped in a hurry, and they also cannot fire without you deciding the previous stage holds up.

The wiring rule: each stage’s own agent declares the handoff to the next. The chain is a list of objects in the carrying agent’s frontmatter - a button label, the target agent, the prompt it arrives with, whether the prompt auto-sends after your click, and an optional per-handoff model override (a cost lever: pin a cheaper model for a mechanical stage) - fields per the VS Code custom agents reference, verified September 2026:

.github/agents/library-reviewer.agent.md

---
name: library-reviewer
description: Reviews changes to shared-lib for breaking changes and API contract violations.
tools:
  - read
  - search
handoffs:
  - label: Audit the consumers
    agent: consumer-audit
    prompt: >-
      Check every consumer of shared-lib against this approved change:
      new exports plus one new check. Report breaks per affected symbol.
    send: false
---

You are a library reviewer for @acme/shared-lib.

When reviewing changes:

1. Check that exported function signatures have not changed in breaking ways.
2. Verify that sort order contracts are documented and tested.
3. Ensure money formatting uses integer cents as input.
4. Flag any new exports that lack corresponding tests.
5. Check that downstream consumers in orders-service are not broken.

Be strict about backwards compatibility. This library is consumed by multiple services.

That is the reviewer’s file with one addition: the handoffs block.

The reviewer declares the step to the audit; consumer-audit is the end of the chain and declares nothing. And the plan stage: handoffs is a custom-agent mechanism, so the plan stage simply ends when you start the first custom agent in the chain - the reviewer, opened with a prompt that points at the plan - whose handoffs carry the workflow from there.

The plan comes first

Notice the chain starts with a plan, and that is not incidental. Back in the modes chapter you met the Plan role - Copilot producing a structured approach before writing code, so you could approve the approach while it was cheap to change. For the highest-consequence change in the course, leading with a plan is the only sane opening. You do not want an agent improvising edits to a library many services depend on; you want to see the proposed sequence - what surface gets added, in what order, with what compatibility guarantees - and sign off before a line changes. The plan is what your reviewer reviews and what your consumer audit runs against. Plan first, then review, then audit, then build.

What you built

Step back and look at the team this chapter assembles, because it is the shape of careful work on shared code:

• A reusable reviewer that carries the library’s compatibility rule so you never re-explain it.
• A coordinator that fans subagents across every consumer in isolated context, turning every risky guess into a clean verdict.
• A sequence - plan, review, audit - wired with handoff buttons so the careful steps stand in the right order, each one requiring your click to proceed.

That is reusable, delegated context doing exactly what this part of the course is about: making a change you could not safely make by hand into one you can ship with confidence.

One piece of the library’s knowledge is still living in prose - the audit-event convention (the team’s agreed procedure for recording significant events), and the specific shape of the approval.requested / approval.granted events the library is gaining. Right now it lives in your reviewer’s instructions and your head. The next chapter packages that convention into something portable that both repos can use, and that works across more than just Copilot. Next chapter: Skills.