Create Templates

Goal	Use
Customize a known pattern	atomize template create --from <name>
Build with prompts	atomize template create --scratch
Draft from prose	atomize template create --ai
Capture existing team practice	atomize template create --ai --reference docs/how-we-work.md (see Reference Documents)
Reuse task groups across templates	atomize template create --type mixin

Running atomize template create without flags opens an interactive mode selector.

In VS Code, write the YAML yourself with schema support: see Author Directly In VS Code.

To draft a Template from a description instead, see Draft and improve with AI for VS Code or the CLI.

Start from the Catalog

This is usually the fastest path for a first team-specific template.

atomize template list
atomize template create --from backend-api

Atomize asks how to use the source:

• Inheritance link saves a small Template with extends: "template:backend-api", your name and description, and any Mixins you choose. It picks up later changes to the source each time it's resolved.
• Flat copy saves every field, so the Template is self-contained. You can customize it in the wizard first. It records the source as its origin, but no longer changes when the source does.

atomize template create --from backend-api --save-as my-backend-api

Built-in Templates and Mixins are examples of task breakdowns and Atomize features, rather than recommended team processes. Copy one and adapt its Work Item types, tasks, dependencies, conditions, and estimates. Activities, assignment choices, validation limits, and estimates are illustrative. Match activity names and Work Item types to your project. Mixin percentages add to the consuming Template, so rebalance the combined total and any validation limits.

Built-in Template	Demonstrates
feature-development	Percentage estimates, dependencies, activities, parent-assignee and unassigned tokens, and percentage-total validation
bug-fix	Fixed Task Estimates independent of the Story Estimate, and Task Estimate range validation
agile-story-breakdown	Conditional tasks and percentages, with a commented saved-query selection alternative
backend-api	Factor conversion before percentage distribution and rounding, with a commented non-linear table alternative

The schema supports strategy: percentage; fixed Task Estimates use estimationFixed on individual tasks. Conversion factors and tables translate the Story Estimate before its percentage distribution. Replace the saved-query path before enabling that alternative.

Personal and project-scoped templates can also be used as sources.

Build With The Wizard

Use the wizard when you want full control without writing YAML from scratch.

atomize template create --scratch

The wizard walks through:

1. Basic information: name, description, author, tags
2. Filter configuration: work item types, states, tags, paths, saved queries, and custom fields. With a saved query, the wizard still asks which work item types the query returns. It uses them only to look up fields, not to filter.
3. Task configuration: titles, descriptions, estimation, assignments, dependencies, and conditions. The advanced options ask how many identical Tasks to create; a repeated task skips the dependency question, and if it goes over the limit of 20, the preview offers to raise validation.maxRepeat
4. Estimation settings: the Story field that holds the estimate, how it converts to hours (one-to-one, a factor, or a table of values such as T-shirt sizes), the task type and target fields, what to do when a Story has no usable estimate, what happens when the percentages don't add up to 100%, rounding, and the minimum Task Estimate. With a Connection Profile, field and value choices come from your project instead of typed input.
5. Validation rules: task count and total-estimation expectations
6. Metadata: category, guidelines, and notes

After previewing the generated YAML, save it to the template catalog or cancel without writing anything.

Author Directly In VS Code

Use .atomize.yaml, .atomize.yml, or a first-line # atomize-yaml marker for the full editor experience.

VS Code provides schema-backed completions, hovers, snippets, diagnostics, CodeLens actions, preview panels, and generation panels.

Minimal template:

formatVersion: "1.0"
name: "Feature Breakdown"

filter:
  workItemTypes: ["User Story"]
  states: ["New", "Active"]

tasks:
  - title: "Design: ${story.title}"
    estimationPercent: 20
  - title: "Build: ${story.title}"
    estimationPercent: 60
  - title: "Validate: ${story.title}"
    estimationPercent: 20

When a Story needs several identical Tasks, such as one review per developer, use repeat instead of copying the task (the atm-task-repeat snippet inserts one):

tasks:
  - title: "Build: ${story.title}"
    estimationPercent: 60
  - title: "Add review conclusions"
    estimationPercent: 10
    repeat: 4        # "Add review conclusions (1)" to "(4)", 10% each

See Repeated Tasks and the worked example examples/repeated-review-tasks.atomize.yaml.

Validate and preview often:

atomize validate my-template.atomize.yaml --strict
atomize generate my-template.atomize.yaml --platform mock

Create Mixins

Mixins are reusable groups of tasks that templates can include through the mixins: field.

atomize template create --type mixin
atomize template create --type mixin --save-as security-review

Use mixins for task groups that appear across many templates, such as security review, documentation, accessibility, release checks, or testing standards.

To inspect a composed template:

atomize template resolve template:my-feature --validate

See Template Reference - Composition.

Next steps

Check field rules in the Schema Reference, learn how a Template is structured, then install it in a Catalog or share it with your team.