Azure DevOps Work Items Explorer

Explore and manage Epics, Features, User Stories, and Tasks in an Azure DevOps project using az boards CLI commands. Five modes: overview, get epic, get feature, create, and edit.

Announce at start: "I'm using the azure-devops-workitems skill to work with Azure DevOps work items."

Prerequisite: az CLI + azure-devops extension + active login. If missing, use the azure-devops-cli skill to set up first.

---

Project Resolution (all modes)

Used at the start of every mode to determine the target project:

1. If the user provides a project name, use it (pass --project <name>)
2. Else read default: az devops configure --list | grep project
3. If no default set, ask the user

---

Mode 1: Overview (Tree)

Display the full work item hierarchy for a project.

Steps:

1. Resolve project
2. Query all Epics:

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo] FROM WorkItems WHERE [System.WorkItemType] = 'Epic' AND [System.TeamProject] = '@project' ORDER BY [System.Id]" --project <project> -o json

3. For each Epic, fetch child Features via relations:

az boards work-item show --id <epic_id> --expand relations -o json

Parse relations array for entries where rel == "System.LinkTypes.Hierarchy-Forward". Extract child IDs from the url field (last path segment), then fetch each child. Note: the item id is at the top level of the response (not inside fields).

4. For each Feature, fetch child User Stories/Tasks the same way.

5. Display as an indented tree:

Epic #1234 [Active] - Platform Modernization (Assigned: Alice)
  Feature #1235 [Active] - Migrate to new API (Assigned: Bob)
    Story #1240 [New] - Implement auth endpoint (Assigned: Carol)
    Task #1241 [Active] - Write unit tests (Assigned: Dave)
  Feature #1236 [Resolved] - Update CI pipeline (Assigned: Eve)

Fields per line: ID, State, Title, Assigned To

---

Mode 2: Get Epic

Show detailed info for a specific Epic and its child Features.

Steps:

1. Resolve project
2. If Epic ID provided, fetch it directly. If not, search by title:

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.WorkItemType] = 'Epic' AND [System.Title] CONTAINS '<search_term>' AND [System.TeamProject] = '@project'" --project <project> -o json

If multiple matches, let the user pick.

3. Fetch the Epic with relations:

az boards work-item show --id <epic_id> --expand relations -o json

4. Display the Epic detail card:

   • ID, Title, State, Assigned To
   • Iteration Path, Area Path, Tags, Priority
   • Description (strip HTML to plain text)

5. List child Features in a table below:

   • ID, Title, State, Assigned To, Iteration Path

---

Mode 3: Get Feature

Show detailed info for a specific Feature, its child User Stories, and their child Tasks.

Steps:

1. Resolve project
2. If Feature ID provided, fetch directly. If not, search by title:

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.WorkItemType] = 'Feature' AND [System.Title] CONTAINS '<search_term>' AND [System.TeamProject] = '@project'" --project <project> -o json

If multiple matches, let the user pick.

3. Fetch the Feature with relations:

az boards work-item show --id <feature_id> --expand relations -o json

4. Display the Feature detail card:

   • ID, Title, State, Assigned To
   • Iteration Path, Area Path, Tags, Priority
   • Description (strip HTML to plain text)

5. Fetch child User Stories via Hierarchy-Forward relations.

6. For each User Story, fetch child Tasks via Hierarchy-Forward relations.

7. Display as an indented tree below the card:

User Story #2001 [Active] - As a user I can login (Assigned: Alice)
  Task #2010 [Active] - Implement login API (Assigned: Bob)
  Task #2011 [New] - Write login tests (Assigned: Carol)
User Story #2002 [New] - As a user I can reset password (Assigned: Dave)
  Task #2020 [New] - Design reset flow (Assigned: Eve)

Fields per line: ID, Work Item Type, State, Title, Assigned To

---

Mode 4: Create Work Item

Create a new Epic, Feature, User Story, or Task.

Steps:

1. Resolve project
2. Determine work item type (ask if not specified)
3. For non-Epic types, get the parent ID (mandatory):
   • Feature -> must have a parent Epic
   • User Story -> must have a parent Feature
   • Task -> must have a parent User Story
   • Do not create a Feature, User Story, or Task without a parent
4. Gather fields: Title (required) + optional fields below

Defaults

Field	Default
Assigned To	Current logged-in user (resolve via az account show --query "user.name" -o tsv)
Area Path	NLASTIC\Data Engineering
Iteration Path	NLASTIC (backlog)
Effort	2 (Feature only — see Estimation section below)
Description	TBD (if user does not provide one — see Description section below for format)

Estimation

1 story point = 1 working day = 6 net working hours.

Feature — Effort field (Microsoft.VSTS.Scheduling.Effort):

• Measured in story points
• Default: 2 (= 2 working days / 12 net hours)
• Set to 2 unless the user specifies a different value

User Story — Story Points field (Microsoft.VSTS.Scheduling.StoryPoints):

• Measured in story points
• Default: same as the parent Feature's Effort (2 if not specified)

Task — Original Estimate field (Microsoft.VSTS.Scheduling.OriginalEstimate):

• Measured in working hours
• No default — derive from the parent Feature's Effort when possible (e.g., a Feature with Effort 2 = 12 hours, split across its child Tasks)
• If the user provides an estimate, use it as-is

Task — Remaining Work field (Microsoft.VSTS.Scheduling.RemainingWork):

• Measured in working hours
• Always set to the same value as Original Estimate when creating a new Task
• This ensures the burndown chart starts correctly from day one

Description

When the user provides a description (or you compose one based on context), write it in Markdown format. Structure the description with headings, bullet points, bold text, and other Markdown elements as appropriate for the content. This makes descriptions more readable and organized in Azure DevOps.

Example — User Story description:

## Overview

Allow users to reset their password via email link.

## Acceptance Criteria

- User receives a reset link within 60 seconds
- Link expires after 24 hours
- Password must meet complexity requirements

## Notes

Depends on the email service integration from Feature #1235.

Example — Task description:

## Objective

Write unit tests covering the login API endpoint.

## Scope

- **Happy path:** valid credentials return a JWT token
- **Error cases:** invalid password, locked account, expired session
- **Edge cases:** concurrent login attempts

If the user does not provide a description, use the default TBD.

Area Path

Default: NLASTIC\Data Engineering.

Before creating, explore sub-Area Paths and suggest a more specific one based on the work item context:

az boards area project list --project NLASTIC --depth 3 -o json

The response is a tree with path and children fields. Walk the tree to find nodes under Data Engineering. Suggest the best match based on the work item context. Use the default NLASTIC\Data Engineering if the user accepts or no better match exists.

Iteration Path

Default: NLASTIC (backlog-level, no sprint).

If the user indicates the item is for the current sprint, resolve it:

az boards iteration team list --team "Data Engineering" --project NLASTIC -o json

Each entry has path and attributes.startDate/attributes.finishDate. Find the iteration whose date range contains the current date (match by current month and year). Sprints are named by month (e.g. NLASTIC\March 2026). If no exact match, show available sprints and let the user pick.

Confirmation before create

Before executing, display a summary of all fields and ask for confirmation:

About to create:
  Type:           Feature
  Title:          Migrate to new API
  Assigned To:    bnachlieli@nvidia.com  (from az account)
  Area Path:      NLASTIC\Data Engineering
  Iteration Path: NLASTIC
  Effort:         2 story points  (= 2 working days / 12 net hours)
  Priority:       2
  Parent:         Epic #1234
  Description:    TBD

Proceed? (yes / no / edit fields)

Only execute after the user explicitly confirms. If the user says no or wants edits, let them adjust and re-show the summary.

Create command

Step 1 — Create the work item (without description):

az boards work-item create \
  --type "<Type>" \
  --title "<Title>" \
  --project "<Project>" \
  --fields "System.AssignedTo=<user>" \
           "System.IterationPath=<iteration>" \
           "System.AreaPath=<area>" \
           "System.Tags=<tags>" \
           "Microsoft.VSTS.Common.Priority=<1-4>" \
  -o json

For Features, add Effort (story points):

           "Microsoft.VSTS.Scheduling.Effort=<story_points>"

For User Stories, add Story Points:

           "Microsoft.VSTS.Scheduling.StoryPoints=<story_points>"

For Tasks, add Original Estimate and Remaining Work (hours) if provided:

           "Microsoft.VSTS.Scheduling.OriginalEstimate=<hours>" \
           "Microsoft.VSTS.Scheduling.RemainingWork=<hours>"

Capture the new work item id from the JSON response.

Step 2 — Set the description in Markdown format via REST API:

The az boards CLI stores descriptions as HTML by default. To store the description as rendered Markdown, use the REST API with multilineFieldsFormat:

az rest --method patch \
  --uri "https://dev.azure.com/<org>/<project>/_apis/wit/workitems/<id>?api-version=7.1-preview.3" \
  --resource "499b84ac-1321-427f-aa17-267ca6975798" \
  --headers "Content-Type=application/json-patch+json" \
  --body '[
    {"op": "add", "path": "/fields/System.Description", "value": "<markdown_description>"},
    {"op": "add", "path": "/multilineFieldsFormat/System.Description", "value": "Markdown"}
  ]'

Resolve <org> and <project> from the configured defaults (az devops configure --list). The --resource flag is required for az rest to authenticate against Azure DevOps.

Important: Once a description is saved in Markdown format, it cannot be reverted to HTML.

Link to parent (mandatory for non-Epic types)

az boards work-item relation add \
  --id <new_item_id> \
  --relation-type Parent \
  --target-id <parent_id>

After creation: display the new item's ID, Title, State, URL, Area Path, Iteration Path, and parent link confirmation.

Auto-create hierarchy under Feature

Whenever a Feature is created, automatically create a child User Story and a child Task under it:

User Story:

• Title: same as the Feature title, unless the user specifies a different name
• Story Points: same as the Feature's Effort (default 2)
• Fields: inherit Assigned To, Area Path, Iteration Path, and Description from the Feature
• Link to the Feature as its parent

Task (under the User Story):

• Title: buffer, unless the user specifies a different name
• Original Estimate: converted from the User Story's Story Points (story points x 6 hours) (e.g., 2 story points = 12 hours)
• Remaining Work: same value as Original Estimate
• Fields: inherit Assigned To, Area Path, and Iteration Path from the User Story
• Link to the User Story as its parent

Include all three items in the confirmation summary before creating:

About to create:
  1) Feature: "Migrate to new API"  (Effort: 2 SP, parent: Epic #1234)
  2) User Story: "Migrate to new API"  (Story Points: 2, parent: the new Feature)
  3) Task: "buffer"  (Original Estimate: 12h, Remaining Work: 12h, parent: the new User Story)

Proceed? (yes / no / edit fields)

After all items are created, display all IDs and their parent-child relationships.

---

Mode 5: Edit Work Item

Update fields on an existing Epic, Feature, User Story, or Task.

Steps:

1. Resolve project
2. If item ID provided, fetch it. If not, ask for ID or search by title:

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType] FROM WorkItems WHERE [System.Title] CONTAINS '<search_term>' AND [System.TeamProject] = '@project'" --project <project> -o json

3. Display current values for the item
4. Ask which fields to update

Editable fields

• Title, State, Assigned To, Description
• Iteration Path, Area Path, Tags, Priority
• Effort (Feature), Story Points (User Story), Original Estimate & Remaining Work (Task)

Confirmation before update

Before executing, display a before/after summary and ask for confirmation:

About to update #2001:
  Field           Current                 New
  State           New                     Active
  Priority        3                       2

Proceed? (yes / no / edit fields)

Only execute after the user explicitly confirms. If the user says no or wants edits, let them adjust and re-show the summary.

Update command

For fields other than Description, use the standard update command:

az boards work-item update \
  --id <id> \
  --fields "System.Title=<new_title>" \
           "System.State=<new_state>" \
           "System.AssignedTo=<user>" \
           "Microsoft.VSTS.Common.Priority=<1-4>"

For Features, add Effort if updating:

           "Microsoft.VSTS.Scheduling.Effort=<story_points>"

For User Stories, add Story Points if updating:

           "Microsoft.VSTS.Scheduling.StoryPoints=<story_points>"

For Tasks, add Original Estimate and/or Remaining Work if updating:

           "Microsoft.VSTS.Scheduling.OriginalEstimate=<hours>" \
           "Microsoft.VSTS.Scheduling.RemainingWork=<hours>"

If updating the Description, use the REST API to set/preserve Markdown format:

az rest --method patch \
  --uri "https://dev.azure.com/<org>/<project>/_apis/wit/workitems/<id>?api-version=7.1-preview.3" \
  --resource "499b84ac-1321-427f-aa17-267ca6975798" \
  --headers "Content-Type=application/json-patch+json" \
  --body '[
    {"op": "replace", "path": "/fields/System.Description", "value": "<markdown_description>"},
    {"op": "add", "path": "/multilineFieldsFormat/System.Description", "value": "Markdown"}
  ]'

Use "op": "replace" when the description already has a value, "op": "add" for new descriptions. Both commands can be combined in a single turn if updating description alongside other fields.

After update: show a before/after comparison of changed fields and confirm success.

Common state transitions

Type	States
Epic / Feature	New, Active, Resolved, Closed
User Story	New, Active, Resolved, Closed
Task	New, Active, Closed

---

Quick Reference

Task	Command
Query work items	az boards query --wiql "..." --project <project>
Show work item	az boards work-item show --id <id> --expand relations
Create work item	az boards work-item create --type <type> --title "<title>" --fields ...
Update work item	az boards work-item update --id <id> --fields ...
Link parent	az boards work-item relation add --id <id> --relation-type Parent --target-id <pid>
List area paths	az boards area team list --team "<team>" --project <project>
List iterations	az boards iteration team list --team "<team>" --project <project>