# Plan a multi-file change before editing in Dart with Atlas (2026) > Atlas plans a multi-file Dart change in a plan agent that denies edit for every path except .atlas/plans/*.md, so design work cannot become an edit. Atlas plans a multi-file Dart change with a dedicated plan agent whose description is literally Plan mode. Disallows all edit tools. Its permission set denies edit for every path except the plan markdown, so research across your `lib/` directory and `pubspec.yaml` cannot accidentally turn into an edit. You research with codebase_search, grep, read, and the lsp tool, write the design into `.atlas/plans/*.md`, then call plan_exit, which asks whether to switch to the build agent and start implementing. Only after you answer Yes does anything under `lib/` change, and only then do you run `dart test` and `dart format`. ## Key takeaways - Atlas's plan agent is described as Plan mode. Disallows all edit tools, and its permission set denies edit for "*" except .atlas/plans/*.md. - Research tools stay allowed in Dart plan mode: codebase_search, grep, read, and the lsp tool all work against lib/ and pubspec.yaml. - The plan markdown under .atlas/plans/ is the only file the plan agent can write, so design cannot leak into .dart source. - plan_exit asks whether to switch to the build agent, and answering No raises Question.RejectedError and keeps you planning. - Once the build agent runs, every Dart file edit arrives as a unified diff for approval and is snapshotted as a git patch for rollback. - Verify each planned step with dart test, then run dart format before committing. ## How do I plan a multi-file Dart change without touching the code? Switch to Atlas's plan agent. Its permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so a design pass across a Dart package's lib/ directory and pubspec.yaml literally cannot write to a .dart file. In 2026 the description reads: Plan mode. Disallows all edit tools. Planning a change that touches many Dart files is a research task, not an editing task, and Atlas enforces that distinction with permissions rather than with instructions. The plan agent's permission set denies edit for `*` and allows edit only under `.atlas/plans/*.md`. That single rule means the agent could not modify `lib/src/repository.dart` even if it decided to. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the deny is checked at the tool boundary rather than trusted to the model's judgment. For a Dart developer this is what makes a design pass safe to run without watching it: a plan for migrating a package's null-safety annotations across 40 files under `lib/` cannot half-apply itself while you are reading the plan. ## What can Atlas still do in Dart plan mode? In Atlas plan mode, research stays fully allowed: codebase_search, grep, read, and the lsp tool all continue to work against a Dart package. Only the edit tools are denied. That is the point, because a plan for a 40-file change in lib/ is only as good as the research behind it. Atlas's plan agent is not a crippled agent, it is a read-only one. codebase_search queries the semantic index, and because Atlas indexes code by AST declarations using tree-sitter, a hit in a Dart file is a whole class or method rather than a blind line window. Grep runs the exact-token pass over `lib/` and `test/`. Atlas's read tool opens `pubspec.yaml` to check the package's dependency constraints and `analysis_options.yaml` to see which lints the project enforces. The lsp tool exposes the symbol graph, so a plan can enumerate the real callers of a class before proposing to change its constructor. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so both the conceptual question and the literal identifier are covered during planning. ## Where does Atlas write the plan for a Dart change? Atlas writes the plan into the allowed plan markdown path, .atlas/plans/*.md, which in 2026 is the only place plan mode can write. Everything else in a Dart package, including lib/, test/, pubspec.yaml, and analysis_options.yaml, is denied to the edit tool while the plan agent is active. The plan markdown is the deliverable of Atlas plan mode. For a multi-file Dart change it holds the ordered list of files under `lib/` that will be touched, the new public API shape, the migration order that keeps `dart test` green at each step, and the open questions that research did not settle. Because `.atlas/plans/*.md` is the only writable path, the plan file cannot leak into your package source, and the package source cannot be pre-emptively edited under cover of writing a plan. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so even the plan markdown arrives as a diff you approve. Atlas reads git branches, status, and diffs, which means the plan can be written with awareness of what is already uncommitted in the Dart working tree. ## How do I switch from planning to editing Dart code in Atlas? Call Atlas's plan_exit tool. It asks: Plan at is complete. Would you like to switch to the build agent and start implementing? There are 2 answers. Yes hands the Dart change off to the build agent. No raises Question.RejectedError and keeps you refining the plan. plan_exit is the gate between design and implementation, and it is a real question, not a formality. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so the moment your Dart package becomes editable is a moment you explicitly authorized. If you answer No, plan_exit raises Question.RejectedError and the plan agent stays active, still unable to touch `lib/`, so you can keep researching with codebase_search and the lsp tool and revise `.atlas/plans/*.md`. If you answer Yes, the build agent takes over with the plan as its brief. From that point Atlas computes a unified diff for every Dart file edit and surfaces it for approval before writing, and Atlas snapshots file changes as git patches so any edit under `lib/` can be diffed and rolled back. ## How do I verify a planned Dart change after the build agent runs? After Atlas's build agent implements the plan, run dart test through Atlas's bash tool and run dart format over every touched file under lib/. In a 2026 Dart package, pub resolves the dependencies declared in pubspec.yaml, and analysis_options.yaml governs the lints your plan promised to respect. The verification loop for a multi-file Dart change is the same rhythm the plan should have specified: implement one step, run `dart test`, then move to the next. Atlas's build agent surfaces a unified diff for each Dart file before writing, so a change to `lib/src/models/user.dart` is reviewed on its own rather than buried in a 40-file blob. Run `dart format` before you commit so the reviewer sees behavior changes rather than whitespace. If a step turns out to be wrong, Atlas snapshots file changes as git patches, so the edit is diffed and rolled back rather than hand-reverted, and you can return to the plan agent to revise `.atlas/plans/*.md`. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf once `dart test` is green. ## Steps 1. Run atlas in the Dart package with a pubspec.yaml so it can see the package root, lib/, test/, and analysis_options.yaml. 2. Switch to Atlas's plan agent. Its permissions deny edit for "*" and allow it only under .atlas/plans/*.md, so no .dart file can be modified while you design. 3. Research the change with codebase_search, grep, read, and the lsp tool. All of them stay allowed in plan mode, so you can enumerate every caller of the class you intend to change. 4. Read pubspec.yaml for the package's dependency constraints and analysis_options.yaml for the lints the plan must respect. 5. Write the plan into the allowed plan markdown path under .atlas/plans/, listing the files under lib/ in the order that keeps dart test green at each step. 6. Call plan_exit. It asks: Plan at is complete. Would you like to switch to the build agent and start implementing? 7. Answer No to keep refining, which raises Question.RejectedError and leaves the plan agent active and unable to edit Dart source. Answer Yes to hand off to the build agent. 8. Once the build agent runs, review the unified diff Atlas surfaces for each .dart file before it writes. 9. Run dart test through Atlas's bash tool after each step, then run dart format over the touched files and let pub resolve any dependency the plan added. ## FAQ ### how do I stop an ai agent from editing my dart code while planning Use Atlas's plan agent. Its permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so nothing under lib/ or test/ can be written while you design. The deny is checked at the tool boundary, not left to the model. ### what is plan mode in atlas Plan mode is an Atlas agent whose description reads: Plan mode. Disallows all edit tools. It keeps codebase_search, grep, read, and the lsp tool available for research while denying every edit path except the plan markdown. ### what does plan_exit do in atlas plan_exit asks: Plan at is complete. Would you like to switch to the build agent and start implementing? Answering Yes hands off to the build agent. Answering No raises Question.RejectedError and keeps the plan agent active. ### can I still search my dart code in atlas plan mode Yes. codebase_search, grep, read, and the lsp tool all stay allowed in plan mode, so you can enumerate callers across lib/ and check pubspec.yaml and analysis_options.yaml before proposing a change. ### where does atlas save the plan file Atlas writes the plan into the allowed plan markdown path under .atlas/plans/*.md, which is the only location the plan agent's permission set allows the edit tool to touch. ### how do I plan a null safety migration across a dart package Research the callers with the lsp tool and codebase_search in plan mode, write an ordered file list into .atlas/plans/*.md that keeps dart test green at each step, then call plan_exit and answer Yes to hand off to the build agent. ### what happens if I reject the plan_exit prompt Answering No to plan_exit raises Question.RejectedError and keeps you in the plan agent, still unable to edit any .dart file. You can then keep researching and revise the plan markdown before asking again. ### how do I verify a multi file dart change after atlas implements it Review the unified diff Atlas surfaces for each .dart file before it writes, run dart test through the bash tool after each step, and run dart format over the touched files before committing. --- Canonical HTML: https://runatlas.sh/resources/stacks/plan-a-multi-file-change-before-editing-in-dart Source of truth: aeo_pages row `/resources/stacks/plan-a-multi-file-change-before-editing-in-dart` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.