Plan-First Workflows

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Examples on this page target Claude Code’s plan mode and VS Code’s Copilot Plan mode, both checked against the official Claude Code and VS Code documentation as of 2026-09-28. The running example is again DocsAssistant API, the Spring Boot + Python sample used throughout this sub-section, with its controller at src/main/java/com/example/docsassistant/DocsController.java. This page assumes the basics from Getting Started with Claude Code and Getting Started with GitHub Copilot; it builds on them to cover when and how to plan before an agent starts editing, rather than repeating how to enter each mode.

The explore → plan → implement → commit loop

Letting an agent jump straight from a one-line request to editing files can produce code that solves the wrong problem: a plausible diff for a misunderstood task. Claude Code’s own best-practices guidance recommends separating research and planning from execution, in four phases:

Phase What happens

Explore

The assistant reads the relevant files and answers questions, without proposing or making any change yet.

Plan

The assistant turns that understanding into a concrete, reviewable plan: which files change, what the new behavior is, and how it will be verified.

Implement

Once the plan is approved, the assistant edits files, runs commands and iterates against the plan.

Commit

The assistant stages the result, writes a commit message and, where asked, opens a pull request.
flowchart LR E["Explore"] --> P["Plan"] P --> I["Implement"] I --> C["Commit"]

This loop is most valuable when the change touches several files, the approach is genuinely uncertain, or the codebase is unfamiliar; for a one-line fix you could describe in a single sentence, planning first is overhead rather than a safeguard. A worked, end-to-end example of this exact loop — issue to plan to code to PR — is the catalog’s own Plan skill, part of the Common workflows workflow this sub-section links to rather than re-documenting; see Cloud & Background Agents and Reviewing AI-Generated Code for the parts of that same loop covered on other pages.

In Claude Code
$ claude --permission-mode plan
> read the DocsAssistant API PageRepository and DocsController and understand how pages are
  looked up today; then draft a plan for adding role-based access control so only users with
  the "editor" role can create or delete a page

See Claude Code — Best practices: explore first, then plan, then code.

Spec-first: let the assistant interview you

For a feature large enough that you are still working out the requirements yourself, it helps to have the assistant interview you before it drafts a plan, then capture the answers as a standalone spec file instead of leaving them only in the conversation. A prompt following this pattern, adapted to DocsAssistant API:

In Claude Code
$ claude
> I want to add role-based access control to DocsAssistant API so only editors can create or
  delete a page. Interview me in detail before writing any code: ask about roles, how a caller's
  role is determined, what happens to existing callers with no role, and edge cases I might not
  have considered. Keep asking until we've covered everything, then write the agreed design to
  SPEC.md.

The assistant asks a round of clarifying questions — one at a time or as a short list — rather than guessing at answers, and once you’ve answered enough of them it writes the design to SPEC.md in the repository root: named files and interfaces, what’s explicitly out of scope, and an end-to-end verification step that proves the feature works. Starting a fresh session to implement from that file, rather than continuing the interview session, keeps the implementation’s context focused on the spec instead of the back-and-forth that produced it. See Claude Code — Best practices for this pattern (under "Let Claude interview you").

Claude Code plan mode

Plan mode is the CLI mechanism behind the "plan" phase above: entering it (Shift+Tab until the status bar shows ⏸ plan mode on, or claude --permission-mode plan) restricts the session to reads and exploration until a plan is approved, exactly as Getting Started with Claude Code already covers. What that page doesn’t cover is editing the plan itself once Claude proposes one: pressing Ctrl+G opens the drafted plan in your configured text editor, so you can rewrite a step, add a missing file, or delete something out of scope before approving it, instead of only accepting or asking for a revision in prose. Approving the plan (or pressing Shift+Tab again) switches the session into an editing mode and Claude implements against the approved text:

In Claude Code
> implement the RBAC plan from earlier. write tests for the role check, run the test
  suite and fix any failures.

See Claude Code — Choose a permission mode.

Copilot Plan mode and custom agents

As of 2026-09-28, how planning looks in VS Code depends on which harness runs the session:

  • Copilot sessions have a Plan mode that you toggle with Interactive in the mode picker (or reach by prefixing a prompt with /plan). Copilot researches the workspace, asks clarifying questions and, instead of a diff, presents a plan-review card summarizing the approach, the files it would touch and how it would verify the result. Open Full Plan opens that plan in the Markdown editor, and Submit Feedback sends your comments back to the agent as a request to revise, without approving implementation. From the card you then choose Implement Plan to approve and start right away, Approve Plan Only to approve without executing yet (useful if you want to switch to a cheaper model for implementation), Implement with Autopilot to let it continue autonomously, or Reject to discard it.

  • Local sessions instead use a separate, built-in Plan agent, selected from the agents dropdown (or with /plan), with different controls: Start Implementation switches to the Agent and submits the implementation request (a dropdown next to it can hand the plan off to another destination), Open in Editor creates an editable copy of the plan file, and Start with Autopilot (preview) implements with automatic tool approval.

In GitHub Copilot (VS Code)
/plan Add role-based access control to DocsAssistant API so only editors can create or
delete a page. #DocsController.java #PageRepository.java

For a planning style your team wants to reuse — always name the affected files up front, always list a rollback step, always end with a verification command — VS Code lets you package that as a custom agent: a .agent.md file (created from the Command Palette’s Chat: New Custom Agent command, and stored per workspace under .github/agents/) whose frontmatter names the tools, tool sets and model it’s allowed to use, and whose Markdown body carries the standing instructions. Custom agents were previously documented as "custom chat modes"; the current documentation uses "custom agent" for the same file-backed, shareable mechanism, and a custom agent built for planning can carry required planning deliverables or architectural guidelines as its instructions. See VS Code — Plan work with agents and VS Code — Custom agents for the frontmatter fields a custom agent supports, and Subagents & Custom Agents for the custom-agent mechanism itself in more depth.

Reviewing the plan as a quality gate

A plan is cheap to reject and expensive to have implemented and then unwound, so treat approving one as a real review, not a formality. A short checklist that applies to either tool’s plan:

  • Scope. Does the plan name every file it expects to touch, and does it say what is explicitly out of scope?

  • Correct problem. Does the plan match what you actually asked for, or has it quietly narrowed or widened the task?

  • Edge cases. Does it call out the cases you’d expect for this kind of change (an unknown role, a missing caller, an already-deleted page), not just the common path?

  • Verification. Does the plan end with a concrete way to prove the result works — a test to add, a command to run — rather than "should work"?

  • Risk. Does anything in the plan touch shared code, migrations, or configuration that would be costly to revert if wrong?

If a step fails this checklist, send the assistant back to revise the plan (in Claude Code, describe the change in prose while still in plan mode; in a Copilot session, use the plan-review card’s Submit Feedback) rather than approving it and correcting the implementation afterwards.

Writer / reviewer sessions

For work that matters enough to want a second opinion on the plan or the diff, run two sessions instead of one: one session (the writer) does the work, and a second, independent session (the reviewer) is given only the diff and the criteria to check, not the writer’s reasoning, so it evaluates the result on its own terms. Claude Code’s best-practices guidance documents this as a Writer/Reviewer pattern:

In Claude Code — Session A (Writer)
> Implement role-based access control for DocsAssistant API from SPEC.md
In Claude Code — Session B (Reviewer)
> Review the RBAC implementation in @src/main/java/com/example/docsassistant/DocsController.java
  against @SPEC.md. Look for missing edge cases, an incorrect role check, and anything that
  changed outside the spec's stated scope.

Feeding Session B’s findings back into Session A ("here’s the review feedback: […​]. Address these issues.") closes the loop without you manually diffing the two conversations. The same reviewing-session idea, run as an automated step of the issue → explore → plan → code → PR-review flow instead of by hand, is what the catalog’s Plan and Common workflows document as a worked example — see Orchestration Patterns for how a skill like iru-plan is itself built; Reviewing AI-Generated Code covers reviewing the resulting diff itself in more depth. See Claude Code — Best practices (under "Run multiple Claude sessions").

Related pages

References