work-iterations

Iteration management

This Skill always operates within the scope of aproject.Teamis optional, and is only needed when assigning an Iteration or listing the Iterations of a specific team.

Project selection

If the user provides a project name (for example "Contoso project"), use it directly and do not call the project list API.
If not provided, ask the user once.

If still not provided, list the projects for the user to choose from:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/projects?%24top=500&api-version=7.1"

Team selection

If no team is provided, only performproject-levelactions (list or create the project's Iterations); assigning Iterations waits until there is a team.
If the user requestsassigning an Iteration but does not provide a team, ask for the team name once.

If still not provided, list the teams of the selected project for the user to choose from:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/projects/{project}/teams?%24top=500&api-version=7.1"

Connection and authentication

Always use curl to call the Azure DevOps REST API directly; each command carries its own authentication parameters.

Organization: Read the environment variable AZURE_DEVOPS_ORG(organization name, for example contoso). If it is not set, ask the user once; if the user provides a URL, extract the organization name from https://dev.azure.com/{org} or https://{org}.visualstudio.com .
Token: Send the PAT with Basic authentication:-u ":$AZURE_DEVOPS_PAT"; if only AZURE_DEVOPS_EXT_PATis set (the variable used by the Azure CLI azure-devops extension), use it instead. When using a Microsoft Entra ID token instead, switch to -H "Authorization: Bearer $AZURE_DEVOPS_TOKEN". If neither is set, ask the user to set AZURE_DEVOPS_PAT in their own terminal and retry, then stop. Read the token only from environment variables: do not ask the user to paste the token into the conversation, and do not print it or write it to a file.
PAT scopes: Listing requires only Work Items (Read) and Project and Team (Read); creating and assigning require Work Items (Read & write).
Encoding: URL-encode project, team, and Iteration names in paths (write spaces as %20); in query strings, write $ as %24(for example %24depth) to avoid shell expansion.
Errors: HTTP 401, 403, 203, or an HTML login page in the response means the token is invalid, expired, or lacks sufficient permissions; report it and stop. HTTP 404 means the organization, project, or team name is incorrect.
Windows PowerShell: Call curl.exe(not the curl alias), write environment variables as $env:AZURE_DEVOPS_PAT; PowerShell does not support <<'EOF', so first write the JSON body to a temporary file, then send it with --data-binary "@body.json" .

The two paths for Iterations

Theof a project Iteration (classification node) includes the path level: Iteration .\Contoso\Iteration\Sprint 12。
The paths for team Iterations and the work item do not include it: System.IterationPath .Contoso\Sprint 12。
A classification node has two IDs: the integer id, and the GUID's identifier. When assigning to a team, use identifier。

Rules

1. List the project's Iterations

Useronly requests to list the project's Iterations , retrieve the Iteration classification tree:
```
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/wit/classificationnodes/Iterations?%24depth=10&api-version=7.1"
```
The root node is the project itself; recursively expand children, for each node take name、path、attributes.startDate、attributes.finishDate。
This scenario only reads; it does not create or assign Iterations.
Present as a list, including Iteration names and start and end dates.
When there are no Iterations, clearly state that this project has no Iterations.

Example: "List the Iterations of the Contoso project"

2. List the Iterations of a team in the project

User wantsto list a specific team's Iterations :
```
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/{team}/_apis/work/teamsettings/iterations?api-version=7.1"
```
For each entry take name、path、attributes.startDate、attributes.finishDate、attributes.timeFrame（past、current、future). Only when it is the current Sprint, add &%24timeframe=current。
This scenario only reads; it does not create or assign Iterations.
Present as a list, including Iteration names and start and end dates.
When there are no Iterations, clearly state that this team has no Iterations.

Example: "List the Iterations of the Contoso Team in the Contoso project"

3. Create Iterations for the project

First, follow Rule 1 to retrieve the complete Iteration tree, and from it infer the existing cadence: the length of each Iteration, the interval between Iterations, the naming pattern (for example Sprint 12 → Sprint 13), and which parent node the new Iterations should be placed under.
Plan the new Iterations according to this cadence, skipping items whose names already exist. Before creating, present the planned list (names, start and end dates, parent nodes) to the user for confirmation once.

After confirmation, create them one by one. When placing them at the root level, omit {parentPath}; otherwise fill in the parent node's path relative to the Iteration root (for example 2026 or Release%201）：

curl -sS -u ":$AZURE_DEVOPS_PAT" -X POST -H "Content-Type: application/json" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/wit/classificationnodes/Iterations/{parentPath}?api-version=7.1" \
  -d '{"name":"Sprint 13","attributes":{"startDate":"2026-01-05T00:00:00Z","finishDate":"2026-01-16T00:00:00Z"}}'

The response is the newly created node; note down identifier, to be used later when assigning to teams.

Present the newly created Iterations as a list, including names and start and end dates.
When no Iterations were created, clearly state that no new Iterations were created for this project.

Examples:

"After the last Iteration, create Iterations using the same cadence through the end of 2026"
- Follow Rule 1 to retrieve the complete Iteration tree and infer the cadence.
- Plan the new Iterations according to the cadence, and after user confirmation, create them one by one.
"After the last Iteration, create Iterations using the same cadence through the end of 2026, then assign all these new Iterations to Contoso Team"
- Create the Iterations as in the previous example.
- Use the identifierreturned during creation, and assign them to Contoso Team according to Rule 4.
- Present the newly created Iterations, and note that they have been assigned to the team.

4. Assign Iterations to teams

Determine the project and team according to the rules above.
Find the identifier(GUID) of each Iteration to be assigned: for newly created ones, use the creation response directly; for existing ones, find them from the Iteration tree in Rule 1 by name or date.

Call once for each Iteration:

curl -sS -u ":$AZURE_DEVOPS_PAT" -X POST -H "Content-Type: application/json" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/{team}/_apis/work/teamsettings/iterations?api-version=7.1" \
  -d '{"id":"a589a806-bf11-4d4f-a031-c19813331553"}'

Present the assigned Iterations as a list, including names and start and end dates.
When no Iteration is assigned, explicitly state that this team has no assigned Iteration.

Example:

"Assign Iteration 1, Iteration 2, and Iteration 3 to Contoso Team"
- Find these three Iterations from the Iteration tree identifier, and assign them to the team one by one.
"Assign all Iterations for 2025 and 2026 to Contoso Team"
- Retrieve the complete Iteration tree according to rule 1.
- Find the Iterations whose start and end dates fall in 2025 and 2026.
- Assign them to Contoso Team one by one, and present them as a list.

Present the results

The date format is YYYY/MM/DD. The dates returned by the API are UTC midnight (for example, 2026-01-05T00:00:00Z), take the date part directly, without time zone conversion.startDate、finishDate is null , display (date not set). When inferring the cadence, only use Iterations that have dates.