Draft and improve with AI from the CLI

Describe the Template you need and let Copilot write the first draft, or ask it to propose improvements to an existing Template. You review every draft and proposal before anything is saved.

Before you start

• GitHub Copilot: an active Copilot subscription. Interactive runs start Copilot sign-in when needed. Copilot is not a Connection Profile: see how the Copilot Session works.
• Project Grounding (optional): a Connection Profile with the Project and Team (Read) scope, chosen with --profile or your default profile.
• Wiki pages (optional): the optional Wiki (Read) scope on the same token. Local Markdown and text files need no connection.

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

Draft a Template

Use AI-assisted creation when you can describe the desired workflow but do not want to write the initial YAML. This section covers the CLI. The VS Code extension offers the same as Atomize: Draft Template with AI.

Create a draft. Atomize starts GitHub Copilot sign-in when needed and uses your active Copilot subscription: see Auth Guide for how this Copilot sign-in works and how it differs from a saved connection profile:

atomize template create --ai

For better project-specific output, ground the draft in your Azure DevOps project:

atomize template create --ai --ground --profile work-ado

With --ground, Atomize reads the project's work item types and states, field reference names and allowed values, saved queries, and area and iteration paths through the Connection Profile, and tells Copilot to use only those names instead of inventing its own. The profile's token is used only to read that metadata and is never sent to Copilot. Use --ground when your project has custom fields, non-standard work item types, or saved queries you want the Template to use.

If Atomize can't load the metadata, for example because the token has expired, it asks whether to retry, continue without project metadata, or cancel. It never drops the grounding you asked for without telling you. When you choose AI drafting from the atomize template create menu instead of passing --ai, Atomize asks whether to ground the draft. A non-interactive run stops with an error instead of drafting without the grounding you asked for.

Reference Documents

If your team writes down how it breaks down and estimates work, for example a docs/how-we-work.md in the repo, give it to Copilot as a Reference Document. Drafts and improvements then follow your written process:

atomize template create --ai --reference docs/how-we-work.md
atomize template improve template:backend-api --reference docs/sizing.md --reference docs/definition-of-done.md

Reference Documents must be Markdown (.md) or text (.txt) files inside your workspace. Atomize refuses anything else, including files reached through a link that points outside the workspace. They need no Connection Profile. Copilot treats them as reference material about your process, never as instructions.

If your process lives in an Azure DevOps wiki, use a page from it instead:

atomize template create --ai --reference "wiki:Team.wiki/Process/How we work" --profile work-ado

Atomize reads that page's Markdown through the Connection Profile, and only that page: no sub-pages, no pages it links to, and no images or attachments. In an interactive run, choose Add an Azure DevOps wiki page…, pick the wiki, then filter its page paths and pick the pages you want. Reading wikis needs the optional Wiki (Read) token scope. Without it, Atomize asks you to rotate the token with that scope added, and local files keep working.

To share documents with your whole team, save them as Project Reference Documents in .atomize/ai.yaml and commit it:

referenceDocuments:
  - file:docs/how-we-work.md
  - file:docs/sizing.md

Wiki pages are saved the same way, as wiki:<wiki>/<page path> entries. Every AI run lists them ticked, so you can leave any out of a single run, and --no-project-references leaves them all out. A saved wiki page is used only when the run's Connection Profile reaches that wiki's project; otherwise it's reported as unavailable for that profile and left out, so one ai.yaml works whichever profile a teammate uses. In an interactive run you can add a local file and choose Also save for this project to write it to ai.yaml for you. A saved document that can't be read is reported and left out. A document you named with --reference that can't be read stops the run.

All Reference Documents together are limited to about 24,000 characters, split evenly between them. Space a short document doesn't use goes to the others. If a document has to be shortened, Atomize tells you before anything is sent: an interactive run lets you continue, leave documents out, or cancel. A non-interactive run prints a warning, and template improve --output records it.

Review The Draft

After the grounding and Reference Documents, Atomize asks you to describe the Template, then writes the draft with Copilot. It checks the draft against the Template schema and asks Copilot to fix any problems, up to three attempts.

When you ask for several identical Tasks, such as "one review task per developer, 4 developers", the draft uses a single repeated task instead of four copies.

Atomize shows a preview of the draft and asks what to do next:

• Save template saves it to the Catalog.
• View full YAML prints the draft, then asks again.
• Edit template (opens wizard) opens the draft in the interactive wizard.
• Regenerate starts the draft again from the beginning.
• Cancel discards the draft.

If the draft still has problems after three attempts, Atomize lists them with Copilot's raw output. Choose Edit manually (opens wizard) to continue in the wizard from what Copilot produced, or Cancel.

To improve an existing Template rather than start a new one, use atomize template improve.

Always review AI-generated templates before use:

atomize validate template:<name> --strict
atomize generate template:<name> --platform mock

template improve

Asks Copilot to propose a revision of an existing Template, then shows you the changes before anything is saved.

atomize template improve <template> [options]

<template> is a Catalog ref (template:<name>) or a path to a Template file. Remote Templates must be downloaded first.

Options:

Option	Type	Description
--guidance <text>	string	What the improvement should focus on, such as "tighten the estimates" or "add security reviews". Interactive runs ask for it when you leave it out; press Enter for a general review
--ground	flag	Ground the improvement in your Azure DevOps project's work item types, fields and allowed values, saved queries, and paths
--profile <name>	string	Connection Profile used for grounding (the default profile if omitted)
--reference <path>	string	Send a Reference Document: a Markdown or text file in the workspace, or wiki:<wiki>/<page path> for an Azure DevOps wiki page read through --profile. Repeatable
--no-project-references	flag	Leave out the Project Reference Documents saved in .atomize/ai.yaml
--save-as <name>	string	Save the improvement as a new Template, leaving the source untouched
--scope <scope>	string	With --save-as, the Catalog to save to: user or project. Default: project when the project root has its own .atomize folder, otherwise user.
--overwrite	flag	Replace the source Template with the improvement without asking
--dry-run	flag	Show the proposed changes without saving anything
--strict	flag	Treat validation warnings as errors
--output <file>	string	Write a JSON report of the proposal
-q, --quiet	flag	Suppress non-essential output

What Copilot can change. Copilot looks for clearer Task titles and descriptions, estimation percentages that fit the work, missing test, review or documentation Tasks, and useful conditions, filters, custom fields and dependencies. It works through the same tool-free Copilot Session as template create --ai (see Auth Guide - AI Drafting: Copilot Session).

Grounding. Without grounding, Copilot reviews the Template on its own. With --ground, it also gets your project's work item types, states, field reference names and allowed values, saved queries, and area and iteration paths, and uses only these names when it proposes conditions, custom fields or queries. In an interactive run without --ground, Atomize asks whether to ground the improvement. The profile's token is used only to read from Azure DevOps and is never sent to Copilot. To tell Copilot where the Template doesn't fit how your team works, say so in --guidance (for example "we always end up adding a security review") or give it your written process as a Reference Document.

If grounding you asked for can't be loaded (for example, the token has expired), an interactive run lets you retry, continue without grounding, or cancel. A non-interactive run stops with an error rather than improving without it.

Inherited Templates stay intact. For a Template that uses extends or Mixins, Copilot sees the composed Template so it doesn't suggest Tasks the parent already has. The proposal never changes extends, mixins or origin, and never copies inherited Tasks into the Template. Where an inherited Task deserves a change, Copilot says so in its notes instead, so you can change the parent or Mixin yourself. The proposal is validated composed with its parent, exactly as it will run.

Reviewing and saving. You see the proposed changes (Template fields, and Tasks added, removed, changed or moved) and Copilot's notes. Nothing is saved without your say-so:

• In an interactive run, choose Save changes to the source Template, Save as a new Template, View the full YAML, or Reject.
• --overwrite saves over the source. Your comments, key order and formatting are kept wherever the content didn't change.
• --save-as <name> saves a new Template named "Name (improved)". When the source is a Catalog Template, the new one records it as its origin, so template list shows where it came from. It refuses to replace an existing Template.
• A non-interactive run without --overwrite or --save-as saves nothing.
• Built-in Templates can only be saved with --save-as.

If the proposal still fails validation after Copilot's repair attempts (or has warnings with --strict), nothing is saved. An interactive run lets you retry, save the proposal as a draft file beside the source to fix by hand, or reject it. A non-interactive run exits with code 1.

JSON report (--output):

Field	Description
template	The Catalog ref or file that was improved
ok	Whether the proposal passed validation
diff	The proposed changes: fieldChanges, taskChanges, and identical
validation	valid, errors, and warnings
notes	Copilot's notes on what it changed and why
guidance	The guidance used, or null
referenceDocuments	Each Reference Document sent (ref, title), and whether it was shortened to fit (truncated, originalLength, sentLength)
saved	What was saved (overwrite, save-as, or draft) and where, or null

Examples:

# Review an improvement, then choose what to do
atomize template improve template:backend-api

# Focus the improvement, and save it as a new Template
atomize template improve template:backend-api --guidance "add security reviews" --save-as backend-api-secure

# Ground the improvement in your project and your written process
atomize template improve template:backend-api --ground --reference docs/how-we-work.md --profile work-ado

# Gate an improvement in CI without saving
atomize template improve ./templates/backend.atomize.yaml --dry-run --strict --output improve-report.json

Related

Validate and preview the result with validate and preview, then generate Tasks. If Copilot sign-in, grounding, or a Reference Document fails, see AI template generation fails.