-
-
Notifications
You must be signed in to change notification settings - Fork 75
Planning Workflow
The planning workflow lets you iterate with the agent on what to build before implementation starts. It is driven by the built-in plan primary agent and the /plan slash command.
During planning, the agent can:
- read files and inspect project structure
- search code with grep, structural search, and other read-only tools
- analyze patterns and constraints before proposing changes
- run explicitly safe inspection or validation commands when policy allows
Shell commands in plan mode are validated against a read-only allow-list: rg, ls, cat, grep, find, head, tail, fd, tree, stat, jq, git status|log|diff|show|blame, cargo check|test|clippy, npm|pnpm|yarn test, cd-prefixed read-only chains, and &&/| compositions of read-only segments.
Rejected: file redirections (>), command substitution, ; chaining, in-place edits (sed -i), and any mutating command (rm, mv, cargo build, git push).
Set plan as the default primary agent:
default_primary_agent = "plan"Or use /plan — starts or continues the planning workflow. It is a workflow command, not a session state selector.
Or accept an agent suggestion — execution agents such as build, auto, and duck can propose entering planning via the start_planning tool when a request is demanding or ambiguous. A HITL prompt lets you decide before any edits begin.
- Select the
planprimary agent or run/plan. - Describe the goal and constraints.
- Iterate on repository facts, risks, and open decisions.
- Review the emitted
<proposed_plan>block. - Switch to a build-oriented primary agent (
buildorauto) when ready to implement.
The agent outputs plans in <proposed_plan>...</proposed_plan> blocks. Plans should be decision-complete but sparse (under ~1500 tokens), prefer file:symbol references over prose, and include a verify: check per implementation step.
After a plan is ready, an interactive confirmation popup presents a bounded synopsis and a decision gate:
- Yes, implement this plan — execute in the current context, preserving the session's confirmation policy.
- Yes, clear context and implement — preserve the plan and task tracker, rebuild a fresh execution thread (recommended after long research sessions).
- No, stay in Plan mode — return to planning and revise.
Intent phrases can replace the gate UI: type implement, approve, lgtm, yes/go/start to exit planning and present the plan; stay in planning to keep planning; no/cancel/abandon plan to cancel without implementation.
Approval is accepted only for a persisted plan that passes the artifact validator and has a persisted task tracker. Canonical sections are Summary, Implementation Steps, Test Cases and Validation, and Assumptions and Defaults. Every numbered step must name a concrete target and include a non-empty verify: check. Placeholder tokens and unresolved open questions block approval.
Approval also distills the plan's steps into the task_tracker checklist, which the implementation agent updates as work progresses.
When the planning agent reaches a material ambiguity, it asks through request_user_input — in an interactive session this opens an inline wizard with selectable options. Pressing Esc/Ctrl+C cancels the interview without submitting; the agent may ask again when the ambiguity still matters.
If the planning tool-loop limit is reached, the runloop stops research and asks for one compact, decision-ready plan from the evidence already gathered rather than ending with a loop-limit message.
Drafts always live on disk under .vtcode/plans/<plan>.md — the single source of truth, not chat history. Invalid or partial inline plans are discarded for approval and cannot overwrite an existing valid draft.