azure-devops

This skill provides comprehensive guidance for Azure DevOps automation through purpose-built Python CLI tools that handle:

Work Items (Boards)

• Work item creation with HTML-formatted descriptions
• Work item updates (state, assignments, fields)
• Work item deletion with confirmation
• Parent-child relationship linking
• WIQL query execution
• Work item type and field discovery

Repositories

• Repository listing with details
• Pull request creation with reviewers and work items
• Branch validation
• Clone URL access

Pipelines

• Pipeline listing and execution
• Build monitoring and logs
• Deployment management

Artifacts

• Package feed management
• Package publishing and downloading
• Version management

1. Authentication First

ALWAYS start by checking authentication:

```bash

python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

```

This verifies Azure CLI is installed, you're logged in, org/project are configured, and you have access.

See: [@authentication.md]

2. Common Operations

#### Create Work Item

```bash

python .claude/scenarios/az-devops-tools/create_work_item.py \

--type "User Story" \

--title "Implement feature" \

--description @story.md

```

#### Query Work Items

```bash

python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

```

#### Create Pull Request

```bash

python .claude/scenarios/az-devops-tools/create_pr.py \

--source feature/branch \

--target main \

--title "Add feature"

```

For detailed guidance on specific operations, see:

• [@authentication.md] - Authentication methods (PAT, OAuth, environment variables)
• [@work-items.md] - Work item CRUD operations, field updates, state transitions
• [@queries.md] - WIQL query patterns, filtering, sorting
• [@html-formatting.md] - HTML formatting in work item descriptions/comments
• [@repos.md] - Repository operations, pull request workflows
• [@pipelines.md] - Pipeline triggers, build monitoring, deployment
• [@artifacts.md] - Package management, artifact publishing
• [@HOW_TO_CREATE_YOUR_OWN.md] - Template for creating similar integration tools

| Tool | Purpose | When to Use |

| --------------------- | --------------------- | ----------------------------------------- |

| auth_check.py | Verify authentication | Before any operations |

| create_work_item.py | Create work items | Add User Stories, Tasks, Bugs, etc. |

| update_work_item.py | Update work items | Change state, assignee, fields |

| delete_work_item.py | Delete work items | Remove work items (with confirmation) |

| get_work_item.py | Get work item details | View complete work item info |

| list_work_items.py | Query work items | Find, filter, and list work items |

| link_parent.py | Link parent-child | Create Epic → Feature → Story hierarchies |

| query_wiql.py | Execute WIQL queries | Complex filtering with WIQL |

| format_html.py | Convert to HTML | Format rich descriptions |

| list_types.py | Discover types/fields | Explore available options |

| list_repos.py | List repositories | View all repositories in project |

| create_pr.py | Create pull request | Submit code for review |

Pattern 1: Create Work Item with Parent

```bash

# Create parent work item

python .claude/scenarios/az-devops-tools/create_work_item.py \

--type "Epic" \

--title "Q1 Planning Initiative" \

--description @epic_desc.md

# Output: Created work item #12345

# Create child and link to parent

python .claude/scenarios/az-devops-tools/create_work_item.py \

--type "Feature" \

--title "Authentication System" \

--description @feature_desc.md \

--parent-id 12345

# Output: Created work item #12346 and linked to parent #12345

```

Pattern 2: Query and Update Work Items

```bash

# Find your active work items

python .claude/scenarios/az-devops-tools/list_work_items.py \

--query mine \

--format ids-only

# Update work item state

python .claude/scenarios/az-devops-tools/update_work_item.py \

--id 12345 \

--state "Active" \

--comment "Starting work on this"

```

Pattern 3: Feature Branch to Pull Request

```bash

# List repositories

python .claude/scenarios/az-devops-tools/list_repos.py

# Create pull request

python .claude/scenarios/az-devops-tools/create_pr.py \

--source feature/auth \

--target main \

--title "Add authentication" \

--description @pr_desc.md \

--reviewers "user1@domain.com,user2@domain.com" \

--work-items "12345,12346"

```

Pattern 4: Discover Available Types

```bash

# List all work item types in your project

python .claude/scenarios/az-devops-tools/list_types.py

# Show fields for specific type

python .claude/scenarios/az-devops-tools/list_types.py \

--type "User Story" \

--fields

```

HTML Formatting Required

Azure DevOps work item descriptions use HTML, not Markdown or plain text.

The tools handle this automatically:

• create_work_item.py converts markdown to HTML by default
• Use --no-html to disable conversion
• Or use format_html.py directly for custom formatting

See: [@html-formatting.md]

Two-Step Parent Linking

You cannot specify a parent during work item creation via CLI (Azure limitation).

The tools provide two approaches:

Option A: Use --parent-id flag (recommended):

```bash

python .claude/scenarios/az-devops-tools/create_work_item.py \

--type "Task" \

--title "My Task" \

--parent-id 12345

```

Option B: Link separately:

```bash

# Step 1: Create

TASK_ID=$(python .claude/scenarios/az-devops-tools/create_work_item.py \

--type "Task" \

--title "My Task" \

--json | jq -r '.id')

# Step 2: Link

python .claude/scenarios/az-devops-tools/link_parent.py \

--child $TASK_ID \

--parent 12345

```

Area Path and Work Item Types

• Area path format: ProjectName\TeamName\SubArea
• Work item types vary by project (standard + custom types)
• Use list_types.py to discover what's available in your project

| Error | Tool to Use | Example |

| ---------------------- | --------------------------------------- | ----------------------------- |

| Authentication failed | auth_check.py --auto-fix | Auto-login and configure |

| Invalid work item type | list_types.py | See available types |

| Field validation error | list_types.py --type "Type" --fields | See valid fields |

| Parent link failed | Check IDs exist, verify hierarchy rules | Epic → Feature → Story → Task |

| Branch does not exist | Verify with git branch -a | Push branch first |

All tools are in ~/.amplihack/.claude/scenarios/az-devops-tools/:

• Standalone Python programs (can run independently)
• Importable modules (can use in other scripts)
• Comprehensive error handling
• Tests in tests/ directory

See: [Tool README](~/.amplihack/.claude/scenarios/az-devops-tools/README.md)

These tools follow amplihack principles:

• Ruthless Simplicity: Each tool does one thing well
• Zero-BS: Every function works, no stubs or TODOs
• Reusable: Importable and composable
• Fail-Fast: Clear errors with actionable guidance
• Self-Contained: Standard library + azure CLI wrapper only

```bash

# Setup (first time)

python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

# Create work item

python .claude/scenarios/az-devops-tools/create_work_item.py \

--type "User Story" \

--title "Title" \

--description @desc.md

# Update work item

python .claude/scenarios/az-devops-tools/update_work_item.py \

--id 12345 \

--state "Active"

# Query work items

python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

# Create pull request

python .claude/scenarios/az-devops-tools/create_pr.py \

--source feature/branch \

--target main \

--title "Add feature"

# Discover types

python .claude/scenarios/az-devops-tools/list_types.py

```