Templates

Define Tasks

Development docs · main. Your installed version may differ.

Defines the tasks to create for each matching work item. Tasks are created as child items.

tasks:
  - id: "design"
    title: "Design: ${story.title}"
    description: "Design and planning phase"
    estimationPercent: 20
    activity: "Design"
    tags: ["design"]
    assignTo: "@ParentAssignee"
    priority: 2
    condition:
      field: "tags"
      operator: "contains"
      value: "backend"
    dependsOn: []

See the Task field reference for field types, constraints, estimation options and runtime rules.

Variable Interpolation

Use story data dynamically in task titles and descriptions:

Variable	Description
`${story.title}`	Story title
`${story.id}`	Story ID (e.g., `STORY-123`)
`${story.description}`	Story description
`${story.estimation}`	Story Estimate
`${story.tags}`	Story tags (semicolon-separated)

Example:

tasks:
  - title: "Design API: ${story.title}"
    description: |
      Design the REST API for: ${story.title}

      Story ID: ${story.id}
      Estimation: ${story.estimation} points

Task custom field values also support story custom-field interpolation using moustache syntax:

tasks:
  - title: "Backend Implementation"
    customFields:
      Custom.ReleaseVersion: "{{ story.customFields['Custom.ReleaseVersion'] }}"

Assignment Patterns

The assignTo field supports special patterns in addition to email addresses:

Value	Behavior
`@ParentAssignee`	Inherit assignment from the parent story
`@Inherit`	Same as `@ParentAssignee`
`@Me`	Assign to the currently authenticated user
`@Unassigned`	Leave the task unassigned
`"user@company.com"`	Assign to a specific user by email

tasks:
  - title: "Implementation"
    assignTo: "@ParentAssignee"   # Inherit from story

  - title: "Code Review"
    assignTo: "lead@company.com"  # Specific person

  - title: "Testing"
    assignTo: "@Me"               # Whoever runs the command

Task Custom Fields

Use customFields to set Azure DevOps fields when Atomize creates tasks. Keys are always ADO reference names such as Custom.ClientTier or Microsoft.VSTS.Common.Priority.

tasks:
  - id: "backend"
    title: "Backend Implementation"
    customFields:
      Custom.ClientTier: "Enterprise"
      Custom.ReleaseVersion: "{{ story.customFields['Custom.ReleaseVersion'] }}"
      Custom.IsBillable: true
      Custom.TierRank: 3
      Custom.ReleaseDate: "@Today"

The custom field reference covers reference-name syntax, supported value types and platform validation rules.

Validation behavior:

atomize validate without --profile checks structure only and warns that custom fields were not verified against ADO
atomize validate --profile <name> connects to ADO and validates field names, read-only status, types, and picklist values
atomize generate always validates custom fields against live ADO field metadata before creating work items

Use atomize fields list to browse available field names and types for a project before authoring templates.

Task Dependencies

Define execution order by referencing other task IDs in dependsOn. Atomize creates dependency links between tasks in the platform.

tasks:
  - id: "design"
    title: "Design API"
    estimationPercent: 15

  - id: "implement"
    title: "Implement API"
    estimationPercent: 50
    dependsOn: ["design"]      # Cannot start until "design" is done

  - id: "test"
    title: "Write Tests"
    estimationPercent: 25
    dependsOn: ["implement"]

  - id: "review"
    title: "Code Review & Documentation"
    estimationPercent: 10
    dependsOn: ["implement", "test"]  # Multiple dependencies

Rules:

id is required on any task that other tasks depend on
Give a task that uses dependsOn its own id; a missing ID produces a warning
Circular dependencies are a validation error
IDs must be unique within a template
A repeated task can't use dependsOn, and no task can depend on one

Repeated Tasks

Set repeat to create several identical Tasks from one task definition, for example one review Task per developer. You don't have to copy the task block and keep the copies in sync.

tasks:
  - id: "implement"
    title: "Implement: ${story.title}"
    estimationPercent: 60

  - title: "Add review conclusions"
    estimationPercent: 10
    repeat: 4                  # creates 4 Tasks

Each copy's title ends with its position, so the Story above gets "Add review conclusions (1)" to "Add review conclusions (4)". With repeat unset or 1, the task creates one Task and its title is unchanged.

How a repeated task behaves:

Every copy is identical. All copies share the same description, tags, activity, assignee and custom fields. Write separate tasks when copies need to differ.
Each copy gets the full percentage. Four copies at 10% take 40% of the Story Estimate together. The template above sums to 60% + 4 × 10% = 100%.
A condition applies to all copies. The task's condition is checked once against the Story, so either every copy is created or none is.
Validation counts copies. totalEstimationMustBe, totalEstimationRange, minTasks and maxTasks count each copy, so they describe what generation produces. requiredTasks still matches the task's own title, without the position suffix.
Previews show every copy. Mock Preview, Live Preview and a dry run list each copy with its title and estimate.

Rules:

repeat is a whole number of at least 1.
A repeated task can't use dependsOn, and no task can list a repeated task in its dependsOn. A dependency links two single Work Items, and the copies have no single Work Item to link.
repeat can be at most 20, which guards against a typo creating many Tasks on a live platform. A template that genuinely needs more raises its own limit with validation.maxRepeat.

The count is a fixed number written in the template. It can't come from a Story field and can't be set at generate time.

Authoring:

CLI wizard: the advanced task options ask how many identical Tasks to create.
VS Code: type atm-task-repeat.
AI drafts: a request such as "one review task per developer" produces a repeated task.

Look up fields

tasks: every task field, with types and constraints.
tasks[].assignTo, tasks[].customFields, tasks[].dependsOn, and tasks[].repeat.

To create a task only for some Stories, add a condition. To size each task, see Estimate Tasks.