Choose Stories with filters

Defines which work items this template applies to. All criteria are combined with AND logic.

filter:
  team: "Backend Team"           # Override team from the selected profile
  workItemTypes: ["User Story", "Bug"]
  states: ["New", "Active"]
  statesExclude: ["Done", "Removed"]      # Exclude items in these states
  statesWereEver: ["In Review"]           # Items that were ever in these states
  tags:
    include: ["backend"]
    exclude: ["deprecated"]
  areaPaths: ["MyProject\\Backend"]
  areaPathsUnder: ["MyProject\\Backend"]  # Match area path and all descendants
  iterations: ["MyProject\\Sprint 23"]
  iterationsUnder: ["MyProject\\Release 2"] # Match iteration and all descendants
  assignedTo: ["user@company.com", "@Me"]
  changedAfter: "@Today-7"               # Changed in the last 7 days
  createdAfter: "@Today-30"              # Created in the last 30 days
  priority:
    min: 1
    max: 3
  excludeIfHasTasks: true

See the filter field reference for each criterion's shape, requirements and allowed values.

Special Values

Some filter fields accept special macro values:

Value	Used in	Behavior
"@Me"	assignedTo	Resolves to the currently authenticated user's email
"@TeamAreas"	areaPaths	Resolves to all area paths owned by the configured team
"@CurrentIteration"	iterations	Resolves to the team's current sprint/iteration

Date Filters

changedAfter and createdAfter accept either a literal date string or an @Today macro for relative dates.

@Today macro syntax: @Today, @Today-N, @Today+N

filter:
  changedAfter: "@Today-7"     # Changed in the last 7 days
  changedAfter: "@Today-30"    # Changed in the last 30 days
  createdAfter: "@Today"       # Created today
  createdAfter: "2026-01-01"   # Created on or after a specific date

Other supported macros: @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear (also support ±N offsets)

Area Paths: exact vs. descendants

Use areaPaths for exact matches and areaPathsUnder to include all sub-areas:

# Only items directly in "MyProject\Backend"
filter:
  areaPaths: ["MyProject\\Backend"]

# Items in "MyProject\Backend" AND any sub-area (e.g. "MyProject\Backend\API")
filter:
  areaPathsUnder: ["MyProject\\Backend"]

Iterations: exact vs. descendants

Use iterations for exact matches and iterationsUnder to include all child iterations:

# Only items in Sprint 23
filter:
  iterations: ["MyProject\\Sprint 23"]

# All sprints under Release 2 (e.g. Sprint 1, Sprint 2, ...)
filter:
  iterationsUnder: ["MyProject\\Release 2"]

savedQuery

Delegate query composition entirely to an existing Azure DevOps saved query. Atomize resolves the query via the ADO Queries API, executes its WIQL, and pipes the results into the standard task-creation pipeline.

Reference by ID (most stable: unaffected by renames or moves):

filter:
  savedQuery:
    id: "a1b2c3d4-0000-0000-0000-000000000000"

Reference by path (human-readable, matches the query browser hierarchy):

filter:
  savedQuery:
    path: "Shared Queries/Teams/Backend Team/Sprint Active Stories"

Rules:

• id and path are mutually exclusive: provide exactly one.
• id must be a valid UUID (visible in the ADO query URL).
• Only flat (Work Items) queries are supported. Tree and one-hop queries are rejected at runtime with a clear error.
• savedQuery takes precedence over all structured filter fields (states, tags, area paths, etc.). A validator warning is emitted if both are present.
• workItemTypes is the exception: alongside savedQuery it declares which types the query returns. It never filters the query's results, but Atomize uses it to look up fields: the estimation source and condition field pickers, and Online Validation of those fields. The CLI wizard asks for it when you pick a saved query.

Post-processing still applies: excludeIfHasTasks still applies to the query results after resolution, and you can still cap execution with the CLI --limit option.

filter:
  savedQuery:
    path: "Shared Queries/All Active Stories"
  excludeIfHasTasks: true

atomize generate my-template.yaml --limit 20

Permission requirements:

The PAT used by Atomize must have Work Items (Read) scope on the project containing the query. Only shared queries are accessible: private queries owned by another user will return a "Query not found" error even if the ID is correct.

Permission error reference:

Scenario	Error
Query ID or path does not exist	Query not found: "...". Verify the ID or path and that the query has been shared with your account.
PAT lacks read permission	Access denied to query "...". Ensure your PAT includes the Work Items (Read) scope.
Resolved path is a folder	"..." is a query folder, not a runnable query.
Tree or one-hop query type	Only flat (Work Items) queries are supported. "..." is a tree or one-hop query.

Tip: Use atomize queries list to browse available query paths and IDs without leaving the terminal.

Look up fields

• filter: every criterion, with its shape and allowed values.
• filter.savedQuery: a saved query by ID or path.
• filter.excludeIfHasTasks: skip Stories that already have Tasks.

Browse real query paths and field names with atomize queries list or the VS Code browsers.