Draft and improve with AI in VS Code

Describe the Template you need and let Copilot write the first draft, or ask it to propose improvements to the open Template. Drafts open as unsaved files, and improvements open in the diff editor, so you review everything before it reaches your file.

Before you start

• GitHub Copilot: GitHub Copilot Chat installed and signed in to a Copilot account in VS Code. Copilot is not a Connection Profile, and Atomize stores no Copilot token. See how the Copilot Session works.
• Project Grounding (optional): a Connection Profile with the Project and Team (Read) scope. Without one, choose No project grounding or No grounding.
• Wiki pages (optional): the optional Wiki (Read) scope on the same token. Local Markdown and text files need no connection, only an open workspace folder.

You choose the Grounding for every run. Copilot receives your description or focus, the Template being improved, the project’s names and allowed values, and the Reference Documents you leave ticked. It never receives your token, Stories, or other work items.

Atomize: Draft Template with AI

Drafts a new Template from a description, using the GitHub Copilot account you're signed in to in VS Code. Atomize stores no token, and the AI gets no tools: it can't read your files or reach other services. The first time, VS Code asks you to allow Atomize to use Copilot's language models.

1. Choose how to ground the draft: a Connection Profile, with your workspace default selected first, or No project grounding. With a profile, Atomize reads that project's work item types, states, fields and allowed values, saved queries, and area and iteration paths, and Copilot uses only those names instead of inventing its own. The profile's token is used only to read from Azure DevOps and is never sent to Copilot. If grounding can't be loaded, you choose whether to retry, continue without grounding, or cancel. If you have no profiles yet, you can add one from here.
2. Choose the Reference Documents to send, described below.
3. Describe the Template you need. This comes after the grounding, so you can refer to the documents you chose by name. The box's title summarises the grounding, and it's pre-filled with your last description from this session. For a longer description, use the Open in editor button: your text moves into an untitled Markdown prompt document, where you can write as much as you like, with the chosen documents listed at the top. When you're ready, choose Atomize: Draft Template with AI at the top of that document. It drafts with the grounding you already chose, without asking again.
4. Atomize writes the draft with Copilot. Copilot keeps the task percentages your brief or Reference Documents give, even when they add up to more than 100% (for example when each role estimates its own share). It only makes them add up to 100% when it chooses the split itself, or when you ask it to. A Template above 100% is offered for normalisation when you generate, as usual. Atomize checks the draft against the Template schema, and asks Copilot to fix any problems, up to three attempts. Cancel from the progress notification at any time.
5. The draft opens as a new, unsaved Atomize YAML File, with schema hovers and completions already active. Review and edit it, then save it wherever you like. Nothing is added to your Catalog unless you use Atomize: Install to Catalog. If problems remain after three attempts, they're listed as comments at the top of the file.

To try again, run the command again. To discard a draft, close it without saving.

This command needs GitHub Copilot Chat. If Copilot can't be used, the command tells you why and offers the fix:

• GitHub Copilot Chat isn't installed or signed in: Install GitHub Copilot Chat.
• You declined VS Code's permission prompt: Try Again.
• The model in atomize.ai.model isn't available: Use Automatic or Open Settings.
• The request is too large for the model: leave out some Reference Documents, run without project grounding, or choose a model with a larger limit in atomize.ai.model.

Atomize: Improve Template with AI

Asks Copilot to propose a revision of the open Template, and shows it in VS Code's diff editor next to your file. Run it from the Atomize: Improve with AI CodeLens on a Template, or from the Command Palette. It uses the same Copilot Session as drafting, with no tools and no stored token.

1. If the file has unsaved changes, Atomize asks you to save first. It works from the saved file.
2. Choose how to ground the improvement: a Connection Profile, with your workspace default selected first, or No grounding to review the Template on its own.
   • With a profile, Atomize reads the project's work item types, fields and allowed values, saved queries and paths, so any conditions, custom fields or queries Copilot proposes use names that really exist.
   • The profile's token is used only to read from Azure DevOps and is never sent to Copilot. If grounding can't be loaded, you choose whether to retry, continue without grounding, or cancel.
3. Choose the Reference Documents to send, described below.
4. Optionally say what the improvement should focus on, such as "tighten the estimates" or "add security reviews". This is where to say where the Template doesn't fit how your team works, such as "we always end up adding a security review". It comes after the grounding, so you can refer to the documents you chose by name. The box's title summarises the grounding. Leave it blank for a general review.
5. Copilot reviews the Template. A Template whose percentages add up to more than 100% keeps that allocation unless your focus asks for it to add up to 100%. You can cancel from the progress notification.
6. The diff opens with your file on the left and Copilot's proposal on the right. Only real changes show: your comments, key order and formatting are kept wherever the content didn't change. A notification lists Copilot's notes on what it changed and why.
7. You can edit the right-hand side before deciding. Then use the buttons in the editor title bar:
   • Accept Improvement puts the right-hand side, including your edits, into your file as a single change you can undo. The file is left unsaved, so save it when you're happy.
   • Save Improvement as New Template opens the proposal as a new, unsaved Template named "Name (improved)", leaving your file as it was. When your file is a Catalog Template, the copy records it as its origin.
   • Reject Improvement closes the diff and leaves your file unchanged.

For a Template that uses extends or Mixins, Copilot sees the composed Template but never changes extends, Mixin references or origin, and never copies inherited Tasks into your file. When an inherited Task deserves a change, Copilot says so in its notes so you can change the parent or Mixin yourself. The proposal is validated composed with its parent, exactly as it will run. If Copilot can't fix every problem in its proposal, the notification lists what's left to fix.

Improving never writes to your Catalog. To add an improved copy to it, use Atomize: Install to Catalog.

Reference Documents

Draft and Improve can send your team's written process to Copilot as Reference Documents. Copilot treats them as reference material, never as instructions. After you choose grounding, a list shows the Project Reference Documents saved in .atomize/ai.yaml, all ticked. Untick any to leave them out of this run, then press Enter. The title-bar buttons add more:

• Add a local Markdown or text file: a file dialog for .md and .txt files. They must be inside your workspace, and files reached through a link that points outside it are refused.
• Add an Azure DevOps wiki page: available when you chose a Connection Profile for grounding. Pick the wiki, then filter its page paths and pick the pages. Only each page itself is read: no sub-pages, links, images or attachments.

After adding documents, choose Use for this run only or Also save for this project, which adds them to .atomize/ai.yaml for everyone working in the repo. Editing ai.yaml by hand gives you completion and validation.

A saved wiki page is used only when your Connection Profile reaches that wiki's project; otherwise it's left out as unavailable for that profile. If your token can't read wikis, Atomize asks you to rotate it with the optional Wiki (Read) scope from Manage Profiles, and local files keep working.

All Reference Documents together are limited to about 24,000 characters, split evenly between them. If any have to be shortened, Atomize tells you before sending, and you can continue or leave some out.

Related

Check a draft with schema hovers and Offline Validation and a Mock Preview, inspect a composed result with Show Effective Template, then generate Tasks. For connection problems, see Fix connection problems.