Google Antigravity /plan: create and review an implementation plan

Use /plan <task> to ask Google Antigravity to inspect the workspace, clarify open requirements and draft an Implementation Plan before writing code. Read and comment on that artifact, request revisions through Review, then choose Proceed when ready. Check the review policy first: automatic continuation is possible.

The IDE uses visual artifact controls; CLI review happens in the terminal. agy --mode=plan selects a CLI execution mode rather than sending one slash command. In our editorial comparison, /plan helps settle the approach; Codex /goal pursues completion. Use a normal prompt or Fast Mode for simple, already-defined work.

Adapt the planning template ↓

1. Separate the command, artifact and CLI mode

/plan is a prompt command for exploring a task before implementation. Implementation Plan is the reviewable deliverable describing the proposed changes. plan is also a CLI execution-mode setting that changes how prompts are prepared. They work together but are different user controls.

The command catalog lists Antigravity 2.0 desktop/web and the CLI. The artifact guide also covers Antigravity IDE; its older ide-implementation-plan URL now redirects to that shared guide. Do not assume every IDE extension exposes identical buttons or keyboard shortcuts.

Before trying the CLI, use Google's installation and authentication instructions and open the intended repository. This guide does not run an installer or change your settings.

2. Explore, clarify, then inspect the plan

Enter /plan <task> in the supported prompt input. Plain /plan starts discovery from the current workspace context. The official command guide describes file and dependency exploration, questions where requirements are unclear, and a structured plan.

Use this sequence as an orientation, not a guaranteed state machine. A well-specified task may need little clarification. Review policy affects whether the agent waits:

Prompt → analysis and code exploration → clarification if needed → Implementation Plan → review/comments or policy-controlled continuation → revised plan or implementation.

As a practical review checklist, compare the plan against the actual request: which files change, what stays compatible, how each stage is verified, and which decisions remain unresolved. Google's CLI best practices separates exploration, planning and approved execution, and recommends giving the agent concrete local checks.

3. Comment, Review or Proceed on the right surface

In the visual artifact workflow, open the Implementation Plan, read the proposed changes and add comments to specific passages. Use Review in the artifact header to inspect your comments and submit feedback when you want a revision. Use Proceed in the conversation or artifact header when you intend to move into implementation. Google notes that feedback can lead to another plan revision or further work; describe the requested next action explicitly. Implementation Plan controls.

In the CLI, the artifact panel is a terminal interface. Open it with /artifact or Ctrl+R, select a plan and open its detail view. At a target line, c opens a comment editor and Esc submits that comment. The picker uses y/n to approve or reject the highlighted item. Follow the actual prompt shown rather than looking for a visual IDE Proceed button.

Editorial recommendation: resolve your important comments before approving. Approving a plan is a decision about the proposed work; it is not evidence that the resulting code has passed tests.

4. Check Plan Review Policy before you start

The September 22, 2026, Antigravity 2.17.0 changelog calls the Agent setting Plan Review Policy and describes three behaviors:

Review each plan.
Review when the agent considers it worthwhile.
Skip plan review.

These are descriptions of the behaviors, not a claim about the exact labels on every installation. The changelog warns that releases reach users gradually. This 2.17.0 entry belongs to Antigravity 2.0, not the CLI version series.

The Artifact Review help page still describes the older Request Review and Always Proceed choices. Request Review pauses for approval; Always Proceed bypasses that review pause. The CLI settings reference separately lists artifactReviewPolicy values asks-for-review, agent-decides and always-proceed.

For this guide's review-before-coding task, choose the behavior that requests review every time and confirm it in your installed client. Do not assume typing /plan always forces a manual approval stop. A plan-review preference is separate from permission to execute individual tools.

5. Start CLI plan mode deliberately

The execution-mode guide documents this shell command for one session:

NOT EXECUTED FOR THIS GUIDE

agy --mode=plan

In the prompt box, Shift+Tab cycles default → accept-edits → plan → default. Confirm the mode indicator. Plan mode adds the /plan instruction prefix and uses exploration tools such as code_search, grep_search and view_file before presenting an outline for approval.

For a persistent preference, open /settings and choose Agent Mode. The mode guide also documents agentMode in settings.json. Merge this field into your existing configuration rather than replacing the file:

NOT EXECUTED FOR THIS GUIDE

{
  "agentMode": "plan"
}

The settings guide locates the user file at ~/.gemini/antigravity-cli/settings.json. A launch flag overrides the saved mode for that run. Check the controls shown by your version when saving settings.

6. Avoid relying on legacy /planning

Google's current CLI docs disagree. The execution-mode page says /planning and /fast were removed in 1.1.0, while the CLI reference still lists them. This guide uses /plan and the documented plan execution mode. We did not run either legacy command to settle that discrepancy.

If a command or setting is missing, check your installed version and its command menu against the linked documentation. Do not switch off permission controls to make a planning command work.

7. Choose a prompt, planning or persistent execution

AgentSkillsHub editorial framing: planning helps decide how to do the work; a persistent objective helps keep pursuing an agreed result. This is a useful distinction, not a joint Google/OpenAI definition or a ranking.

Google's command catalog also includes its own /goal. Do not import OpenAI Codex lifecycle commands into Antigravity merely because the name matches. Our Codex /goal guide explains that separate product's persistent-objective workflow.

Editorial comparison of task approaches
Approach	Choose it for
Normal prompt / Fast Mode	A clear local change that can be executed directly within the authorized scope.
Antigravity /plan	Exploration, requirements and a proposed implementation you need to review.
Persistent goal, such as Codex /goal	An agreed, verifiable outcome that may require repeated attempts. It does not supply missing design approval.

8. Adapt an original /plan template

This is an AgentSkillsHub template, not Google's mandatory format. Replace the placeholders and choose a review-required policy before using it. The restrictions below express your requested scope; they do not configure a sandbox or guarantee a pause on their own.

NOT EXECUTED FOR THIS GUIDE

/plan Design <specific change> for <repository or subsystem>.
Inspect the current entry points, dependencies, tests and behavior that must remain intact.
Ask about unresolved requirements; compare alternatives only where a real decision is needed.
Produce an Implementation Plan naming affected modules, ordered changes and a verification check for each stage.
Include migration risks, a rollback approach and decisions needing my approval.
Keep this phase to exploration and the plan artifact: do not edit application code, access production, run destructive operations or use paid external services.
Return the plan for my review before implementation.

9. Four changes worth planning first

These original examples are documentation-based prompts, not tested workflows. Each pairs a request with the evidence to inspect, decisions to resolve and a boundary before implementation. They cover complex refactoring, unfamiliar code, ambiguous requirements, competing designs and changes requiring human review.

Auth / OIDC refactor

/plan Design OIDC verification for our existing session service while preserving current login behavior.

Why plan first: Authentication errors affect access control; the trust model needs review before edits.
Inspect: Token validation, issuer configuration, key caching, expiry handling and auth tests.
Questions to resolve: Which issuers are trusted? What happens during key rotation or an unreachable key endpoint?
Expected artifact: Module map, validation sequence, cache strategy, failure cases and a test matrix.
Proceed boundary: Approve trust and failure-handling decisions first. Permit local implementation only; production secrets and identity-provider changes need separate approval.

Database schema migration

/plan Design a reversible split of the customer address field into structured columns.

Why plan first: Existing readers and stored data may require a staged compatibility period.
Inspect: Schema, query callers, migration conventions and non-sensitive fixtures.
Questions to resolve: How should partial addresses map? Is downtime allowed? Who authorizes the backfill?
Expected artifact: Expand/backfill/switch steps, validation queries, compatibility tests and rollback limits.
Proceed boundary: Review the mapping and recovery plan before generating or running migrations. No production database access or backfill during planning.

Large dependency upgrade

/plan Prepare the reporting package for the approved major-version upgrade of its rendering library.

Why plan first: A major release may change APIs and output across several consumers.
Inspect: Dependency graph, adapters, lockfile scope, upstream migration notes and rendering fixtures.
Questions to resolve: Which target version is approved? Which output differences are acceptable?
Expected artifact: Affected-call-site inventory, staged upgrade sequence and baseline-versus-new output checks.
Proceed boundary: Approve the target and acceptance tests before editing package files. Exclude unrelated upgrades and publishing.

Multi-package architecture change

/plan Propose moving shared validation from duplicated handlers into a common package.

Why plan first: An unfamiliar package graph can hide cycles and competing ownership models.
Inspect: Imports, runtime boundaries, duplicated behavior, build configuration and consumer tests.
Questions to resolve: Who owns the shared API? Must consumers migrate together? Which design needs human sign-off?
Expected artifact: Alternative designs, dependency direction, ordered consumer changes and per-stage verification.
Proceed boundary: Select one design and an explicit package scope before implementation. New infrastructure or wider refactoring requires a separate decision.

10. Do not use /plan for every task

A typo, a variable rename, a small bug with a known fix, one understood shell command or a mechanical local change often needs only a direct request. Google's Fast Mode explanation describes this kind of small, localized work without a dedicated planning phase. Fast Mode in that description is not a recommendation to use the disputed legacy CLI /fast command.

Editorial recommendation: if the user has already supplied a complete implementation specification and authorized execution, do not add another planning round merely for ceremony. Use a plan when it resolves uncertainty or enables a meaningful design decision. Verification and permissions still matter for small tasks.

11. Keep planning and permissions separate

Planning is not a permission grant or a security sandbox. The permissions documentation governs sensitive file, shell, network and tool actions independently; the mode guide says shell permission rules remain in force across execution modes. Sandbox behavior also varies by platform and configuration.

The documented planning phase prioritizes reading and outlining before code edits. That is not a blanket guarantee of zero side effects: it produces an artifact and operates within your existing tool environment. Review the actual file-write and shell permissions as well as the plan policy.

As an editorial boundary, exclude production credentials, paid external API calls, destructive database work, deployment and external messages unless separately authorized. Keep planning in the intended workspace with suitable test data. This guide does not recommend bypassing permission checks. After Proceed, inspect the diff and verification results; use the agent workflow case studies for evidence organization.

FAQ

Does /plan immediately edit application code?

The documented purpose is exploration and planning before code changes. Review policy can allow automatic continuation, so /plan is not an unconditional no-write or manual-approval guarantee.

Is agy --mode=plan the same as typing /plan?

They are related but different controls. /plan is a prompt command; --mode=plan selects the CLI execution mode, which the mode documentation says prepends /plan to prompts.

Which review policy should I use to inspect every plan?

Choose the behavior that requests review for every plan. The 2.17.0 changelog calls the setting Plan Review Policy, while older help pages still use Artifact Review Policy terminology. Check your installed UI.

Should I use /planning in the CLI?

This guide avoids it. The mode guide says the legacy command was removed in 1.1.0, but the reference still lists it. Use /plan or documented mode controls; the legacy behavior was not tested here.

Has AgentSkillsHub tested Review and Proceed?

No. AgentSkillsHub reviewed the current Google Antigravity documentation but did not run a complete /plan → review → Proceed workflow during this editorial review.

Primary sources and verification limits

Source-checked 2026-09-28. We read the Google sources below and the legacy IDE-plan URL that redirects to the shared artifact guide. The command-reference conflict and review-policy naming difference remain visible above. No Antigravity command, comment, Review, Proceed or mode-switch workflow was executed. Website QA verifies this page, not Antigravity runtime behavior.