@jwayong/pi-azure-devops

Azure DevOps integration for Pi coding agent — work items, pipelines, repos, test plans, and more.

Install

pi install npm:@jwayong/pi-azure-devops

Or try without installing:

pi -e npm:@jwayong/pi-azure-devops

Features

• 52 tools — work items, boards, sprints, repos, pull requests, pipelines, test plans, and more
• Dual auth — PAT (ADO_PAT) or Azure CLI (az) with auto-detect
• Dual config — environment variables or .pi/settings.json
• Safety model — open / confirm / readonly (default: confirm)
• Mock mode — work offline with fixture data (ADO_MOCK=1)
• Autocomplete — #1234 work item ID completion
• Skill — ado-workitems with WIQL, board, sprint, capacity, and pipeline reference
• 13 prompt templates — triage, status reports, batch create, review history, sprint health, sprint planning, board review, PR review, PR creator, pipeline status, deploy, test status, test runner
• ~870 tests — comprehensive coverage, all offline

What's Included

Area	Tools	Read	Write
Work Items	CRUD, comments, links, revisions, WIQL queries	6	4
Teams	List teams	1	—
Boards	List boards, get/set board columns	2	1
Sprints	List iterations, get/set sprint assignments	2	1
Capacity	Get/set team member capacity	1	1
Repos	List/get repos, list branches	3	—
Pull Requests	List/get PRs, threads, commits, create/update, comment, vote	4	4
Policies	List policies, get evaluations	2	—
Pipelines	List/get pipelines, list/get runs, artifacts, logs, timeline, run/cancel/retry	7	3
Test Plans	List/get plans, suites, cases, points, runs; create runs, update results	8	2
Config	Doctor (health check)	1	—

Quick Start

1. Set environment variables

export ADO_ORG_URL="https://dev.azure.com/myorg"
export ADO_PROJECT="MyProject"
export ADO_PAT="your-personal-access-token"

Or configure in .pi/settings.json:

{
  "ado": {
    "orgUrl": "https://dev.azure.com/myorg",
    "project": "MyProject",
    "authMethod": "pat",
    "safetyLevel": "confirm"
  }
}

2. Verify connection

> Use the ado_doctor tool to check my ADO configuration

3. Use it

> Query all active bugs assigned to me
> Create a user story titled "Implement login page" with description "..."
> Update work item #1234 state to Closed

4. Use prompt templates

Type / in the prompt editor to see available templates:

Command	Description
/ado-triage [filter]	Triage untriaged work items — suggest priority, area, iteration, assignee
/ado-status-report [group-by]	Generate a status report grouped by state, assignee, iteration, or type
/ado-create-batch <items>	Batch-create work items from a structured list
/ado-review-history <id>	Review revision history with a chronological narrative
/ado-sprint-health [team]	Sprint health check — status, capacity, burndown
/ado-plan-sprint <sprint|next>	Sprint planning — propose work assignment based on capacity
/ado-board-review <board> [team]	Board review — analyze setup and suggest improvements
/ado-pipeline-status [pipeline-id]	Pipeline health check — recent runs, failure analysis
/ado-deploy <pipeline-id> [branch]	Deployment pipeline with pre-deploy safety checks
/ado-test-status [run-id]	Test run status report — pass/fail rates, failure analysis
/ado-test-runner [plan-id]	Create and manage a test run — select plan/suite, record results

Examples:

/ado-triage AND [System.WorkItemType] = 'Bug'
/ado-status-report assignee
/ado-create-batch - Bug: Fix crash [priority:1]  - Task: Update docs
/ado-review-history 1234
/ado-sprint-health Engineering
/ado-plan-sprint next
/ado-board-review Stories Engineering

Authentication

Method	Setup	Best for
PAT	Set ADO_PAT env var	Personal use, CI
Azure CLI	Run az login	Enterprise, Entra ID, managed identity

Auto-detect: tries Azure CLI first, falls back to PAT.

Safety Levels

Level	Behavior
open	No confirmation on mutations
confirm (default)	User confirms before create/update/comment/link operations
readonly	Mutation tools blocked entirely

Set via ADO_SAFETY_LEVEL env var or ado.safetyLevel in settings.

Tools Reference

Read Tools

Tool	Description
ado_doctor	Verify configuration, auth, and connection health
ado_get_work_item	Get a single work item by ID
ado_query_work_items	Search work items using WIQL queries
ado_list_work_item_types	List valid work item types for the project
ado_get_work_item_comments	Get comments/discussion on a work item
ado_get_work_item_revisions	Get revision/change history for a work item
ado_list_teams	List teams in the project
ado_list_boards	List boards for a team
ado_get_board	Get board detail with columns and state mappings
ado_list_iterations	List sprints/iterations for a team
ado_get_iteration_work_items	Get work items in a sprint
ado_get_capacity	Get sprint capacity per member with totals
ado_list_repos	List repositories in the project
ado_get_repo	Get repository detail by ID or name
ado_list_branches	List branches for a repository
ado_list_pull_requests	List pull requests with optional filters
ado_get_pull_request	Get pull request detail
ado_get_pull_request_threads	Get comment threads on a pull request
ado_get_pull_request_commits	Get commits in a pull request
ado_list_policies	List policy configurations
ado_get_policy_evaluations	Get policy evaluation status for a PR
ado_list_pipelines	List YAML pipelines in the project
ado_get_pipeline	Get pipeline detail by ID (YAML path, repo, folder)
ado_list_runs	List pipeline runs with optional filters (pipeline, status, result, branch)
ado_get_run	Get a single pipeline run detail
ado_get_run_artifacts	Get artifacts produced by a pipeline run
ado_get_run_logs	Get log entries for a pipeline run
ado_get_run_timeline	Get stages/jobs/tasks timeline for a pipeline run
ado_list_test_plans	List test plans in the project
ado_get_test_plan	Get test plan detail by ID
ado_list_test_suites	List test suites in a plan
ado_get_test_suite	Get test suite detail by ID
ado_list_test_cases	List test cases in a suite
ado_list_test_points	List test points with execution status
ado_list_test_runs	List test runs with optional filters
ado_get_test_run	Get test run detail with statistics

Write Tools (gated by safety level)

Tool	Description
ado_create_work_item	Create a new work item (type, title, description, fields)
ado_update_work_item	Update fields on an existing work item
ado_add_work_item_comment	Add a comment to a work item
ado_manage_work_item_links	Add or remove relation links between work items
ado_set_board_columns	Reconfigure board columns
ado_set_iteration	Add or remove iteration to/from team
ado_set_capacity	Set sprint capacity for team members
ado_create_pull_request	Create a new pull request
ado_update_pull_request	Update title, description, or status of a PR
ado_add_pull_request_comment	Add a comment to a PR thread
ado_set_pull_request_vote	Set vote on a PR (approve, reject, etc.)
ado_run_pipeline	Queue/trigger a pipeline run
ado_cancel_run	Cancel an in-progress pipeline run
ado_retry_run	Retry a failed pipeline run
ado_create_test_run	Create a test run from plan + suites
ado_update_test_results	Update test case outcomes in a run

Prompt Templates

The package includes 13 prompt templates for common ADO workflows. They're automatically available after installing the package.

Command	Description	Arguments
/ado-triage	Triage untriaged work items	Optional WIQL filter
/ado-status-report	Generate a status report	state, assignee, iteration, or type
/ado-create-batch	Batch-create work items	Bullet list of items
/ado-review-history	Review revision history	Work item ID
/ado-sprint-health	Sprint health check — burndown, capacity, at-risk items	Optional team name
/ado-plan-sprint	Sprint planning with capacity-based assignment	Sprint name or next
/ado-board-review	Board configuration analysis and suggestions	Board ID, optional team
/ado-pr-review	Review a PR — threads, policies, changes summary	PR ID, optional repository ID
/ado-pipeline-status	Pipeline health check — recent runs, failures, duration trends	Optional pipeline ID
/ado-deploy	Run a deployment pipeline with pre-deploy safety checks	Pipeline ID, optional branch/params
/ado-pr-creator	Create a PR — suggest title/description from branch context	Repository ID, source branch
/ado-test-status	Test run status report — pass/fail rates, failure details	Optional run ID
/ado-test-runner	Create and manage a test run — guided workflow	Optional plan ID

Usage

Type /ado- in the prompt editor to see autocomplete suggestions. Each template expands into a step-by-step workflow that uses the ADO tools.

# Triage new bugs
/ado-triage AND [System.WorkItemType] = 'Bug'

# Status report grouped by assignee
/ado-status-report assignee

# Create multiple items at once
/ado-create-batch
- Bug: Fix payment timeout [priority:1, tags:payments;critical]
- Task: Write integration tests for checkout
- User Story: Add refund support

# Review what happened to work item #1234
/ado-review-history 1234

# Review pull request #42
/ado-pr-review 42

# Create a PR from feature branch
/ado-pr-creator repo-webapp feature/login

# Check pipeline health
/ado-pipeline-status 1

# Deploy with safety checks
/ado-deploy 2 release/v2

# Check test run status
/ado-test-status 501

# Create and manage a test run
/ado-test-runner 101

If you installed the package locally (e.g., pi -e ./), the templates are loaded from the prompts/ directory as declared in package.json.

Mock Mode

Work offline without ADO credentials:

ADO_MOCK=1 pi "Show me work item #101"

Or pass { mock: true } to any tool parameter.

Configuration Reference

Environment Variables

Variable	Description
ADO_ORG_URL	Organization URL
ADO_PROJECT	Default project
ADO_PAT	Personal Access Token
ADO_AUTH_METHOD	pat, azure-cli, or auto (default: auto)
ADO_SAFETY_LEVEL	open, confirm, or readonly (default: confirm)
ADO_MOCK	Set to 1 to enable mock mode
ADO_TEAM	Default team name (for boards/iterations/capacity)
ADO_MAX_QUERY_RESULTS	Max query results (default: 100)

Settings (ado key in .pi/settings.json)

Key	Type	Default	Description
orgUrl	string	—	Organization URL
project	string	—	Default project
team	string	—	Default team name
authMethod	string	"auto"	pat, azure-cli, or auto
safetyLevel	string	"confirm"	open, confirm, or readonly
defaultWorkItemType	string	"User Story"	Default type for create
maxQueryResults	number	100	Max query results
autocomplete	boolean	true	Enable #id completion

Precedence: env vars → settings.json → defaults

Development

git clone https://github.com/jwayong/pi-azure-devops.git
cd pi-azure-devops
npm install
npm run build
npm test

# Test locally with pi
pi -e ./

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

License

MIT