Template structure

A Template is a YAML recipe for breaking a Story into Tasks. A Mixin is a reusable group of tasks that Templates can include. This page explains how a file is organised and identified. Use the guides beside it for each part’s behaviour, and the Schema Reference for every field’s type, default, and constraints.

Overview

Templates are YAML files that define how Atomize breaks down user stories into tasks. Each template specifies:

1. Which work items to target (via filter)
2. What tasks to create (via tasks)
3. How to distribute estimations (via estimation)
4. Optional constraints (via validation)
5. Optional metadata (via metadata)

---

File Identity

A file's Format Version identifies the edition of the Atomize format it follows. A file without formatVersion is format 1.0, and a release of Atomize that can't read a file's Format Version reports an error naming the versions it reads. Its Revision belongs to the author: Atomize displays it without interpreting or comparing it, and a child Template does not inherit its parent's Revision. Quote version-like strings in YAML so they remain strings.

Use the Template field reference for identity, author and discovery fields, or the Mixin reference when authoring a Mixin.

File Naming

The VS Code extension identifies Atomize files to enable schema autocomplete, CodeLens, snippets, and diagnostics. There are two ways to opt a file in:

Option 1: .atomize.yaml extension (recommended)

Name your file with the .atomize.yaml (or .atomize.yml) extension:

my-team-feature.atomize.yaml
sprint-review.atomize.yaml
security-mixin.atomize.yaml

The Atomize VS Code extension recognises this extension as a durable opt-in and maps it to VS Code's YAML language service so schema hovers and autocomplete work. Templates created by the CLI wizard are stored with this extension automatically.

Option 2: Modeline

If you cannot rename the file (e.g. the name is constrained by another tool or convention), add # atomize-yaml as the very first line:

# atomize-yaml
formatVersion: "1.0"
name: "My Template"
...

The modeline works for any .yaml or .yml file regardless of name. The atm-template and atm-mixin snippets insert it automatically when you scaffold a new template in VS Code.

Content detection fallback

If a file has neither the .atomize.yaml extension nor the modeline, the extension will attempt to identify it by structure (Template: tasks: with filter: or formatVersion: at root; Mixin: tasks: + nested id:, with formatVersion: or no version:). When a file is matched this way, VS Code will show a warning offering to add the modeline or rename the file. Adopting one of the explicit conventions is always preferred: content detection is a fallback and cannot be as precise.

Continue

• Choose Stories with filters to target the right work items.
• Define Tasks, then add conditions and estimate Tasks.
• Compose Templates from a base Template and Mixins.
• See everything together in the complete example.

Look up fields

• formatVersion and version: Format Version and Revision.
• name and the other Template identity fields, or the Mixin fields.