azure-devops

Azure DevOps Skill

Complete Azure DevOps integration covering boards, repositories, pipelines, and artifacts.

Auto-activates when: User mentions Azure DevOps, ADO, work items, boards, repos, pipelines, artifacts, or Azure DevOps URLs.

Purpose

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

Quick Start

1. Authentication First

ALWAYS start by checking authentication:

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

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Implement feature" \
  --description @story.md

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"

Progressive Loading References

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

Available 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

Common Patterns

Pattern 1: Create Work Item with Parent

# 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

# 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

# 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 "[email protected],[email protected]" \
  --work-items "12345,12346"

Pattern 4: Discover Available Types

# 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

Critical Learnings

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):

python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --parent-id 12345

Option B: Link separately:

# 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 Recovery

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

Tool Implementation

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

Philosophy

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

Quick Reference

# 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