pi-azure-devops

Azure DevOps integration for the pi coding agent — work items, boards, repos, pull requests, pipelines, and test plans.

Forked from jwayong/pi-azure-devops and extended by Patrick Weppelmann with additional prompt templates, GitHub Actions CI/CD, auto-generated config template, and enhanced documentation.

All configuration is stored in ~/.pi/agent/pi-azure-devops.json — no environment variables needed.

Installation

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

Or from local path during development:

pi install /path/to/pi-azure-devops

Quick Start

1. Create ~/.pi/agent/pi-azure-devops.json with your org, project, and PAT
2. Run azure_devops_doctor to verify connectivity
3. Start querying work items, repos, pipelines, etc.

Example Configuration

{
  "orgs": [
    {
      "name": "my-org",
      "url": "https://dev.azure.com/my-org",
      "projects": [
        {
          "name": "MyProject",
          "pat": "your-personal-access-token-here"
        }
      ]
    }
  ]
}

Multi-Org / Multi-Project

{
  "orgs": [
    {
      "name": "my-company",
      "url": "https://dev.azure.com/my-company",
      "projects": [
        { "name": "ProjectA", "pat": "token-for-project-a" },
        { "name": "ProjectB", "pat": "token-for-project-b" }
      ]
    },
    {
      "name": "client-xyz",
      "url": "https://dev.azure.com/client-xyz",
      "projects": [
        { "name": "ClientApp", "pat": "client-specific-token" }
      ]
    }
  ]
}

Tools

Work Items

Tool	Description
azure_devops_doctor	Verify configuration and connection health
azure_devops_get_work_item	Fetch a single work item by ID
azure_devops_query_work_items	Search work items using WIQL
azure_devops_list_work_item_types	List valid work item types
azure_devops_get_work_item_comments	Get discussion on a work item
azure_devops_get_work_item_revisions	Get revision history
azure_devops_create_work_item	Create a new work item
azure_devops_update_work_item	Update fields on a work item
azure_devops_add_work_item_comment	Add a comment
azure_devops_manage_work_item_links	Add or remove links

Boards & Sprints

Tool	Description
azure_devops_list_teams	List teams in the project
azure_devops_list_boards	List boards for a team
azure_devops_get_board	Get board detail (columns, WIP limits)
azure_devops_set_board_columns	Reconfigure board columns
azure_devops_list_iterations	List sprints/iterations
azure_devops_get_iteration_work_items	Get work items in a sprint
azure_devops_get_capacity	Get sprint capacity
azure_devops_set_iteration	Add/remove sprint from team
azure_devops_set_capacity	Set team member capacity

Repos & Pull Requests

Tool	Description
azure_devops_list_repos	List repositories
azure_devops_get_repo	Get repository details
azure_devops_list_branches	List branches
azure_devops_list_pull_requests	List pull requests
azure_devops_get_pull_request	Get PR details
azure_devops_get_pull_request_threads	Get PR comment threads
azure_devops_get_pull_request_commits	Get PR commits
azure_devops_list_policies	List branch/PR policies
azure_devops_get_policy_evaluations	Check PR policy status
azure_devops_create_pull_request	Create a pull request
azure_devops_update_pull_request	Update PR (title, status)
azure_devops_add_pull_request_comment	Comment on a PR
azure_devops_set_pull_request_vote	Vote on a PR

Pipelines

Tool	Description
azure_devops_list_pipelines	List YAML pipelines
azure_devops_get_pipeline	Get pipeline detail
azure_devops_list_runs	List pipeline runs
azure_devops_get_run	Get run detail
azure_devops_get_run_artifacts	Get run artifacts
azure_devops_get_run_logs	Get run logs
azure_devops_get_run_timeline	Get stages/jobs/tasks timeline
azure_devops_run_pipeline	Queue a pipeline run
azure_devops_cancel_run	Cancel a run
azure_devops_retry_run	Retry a failed run

Test Plans

Tool	Description
azure_devops_list_test_plans	List test plans
azure_devops_get_test_plan	Get test plan detail
azure_devops_list_test_suites	List test suites
azure_devops_get_test_suite	Get test suite detail
azure_devops_list_test_cases	List test cases
azure_devops_list_test_points	List test points
azure_devops_list_test_runs	List test runs
azure_devops_get_test_run	Get test run detail
azure_devops_create_test_run	Create a test run
azure_devops_update_test_results	Update test outcomes

Commands / Prompt Templates

Command	Description
/azure-devops-doctor	Check Azure DevOps configuration, auth, and connection health
/azure-devops-triage [filter]	Triage untriaged work items
/azure-devops-status-report [group]	Status report by state, assignee, etc.
/azure-devops-create-batch <items>	Batch-create work items
/azure-devops-review-history <id>	Review revision history
/azure-devops-sprint-health [team]	Sprint health check
/azure-devops-plan-sprint <sprint|next>	Sprint planning
/azure-devops-board-review <board> [team]	Board configuration review
/azure-devops-pipeline-status [id]	Pipeline health check
/azure-devops-deploy <id> [branch]	Deployment with safety checks
/azure-devops-pr-review <id>	Pull request review
/azure-devops-pr-creator <repo> <branch>	Create a pull request
/azure-devops-test-status [run-id]	Test run status report
/azure-devops-test-runner [plan-id]	Create and manage a test run

Configuration

All settings are stored in ~/.pi/agent/pi-azure-devops.json.

Key	Type	Default	Description
orgs	array	—	List of org configurations
orgs[].name	string	—	Display name for the org
orgs[].url	string	—	Org URL (e.g. https://dev.azure.com/myorg)
orgs[].safetyLevel	string	—	Safety level override for all projects in this org
orgs[].projects	array	—	Projects in this org
orgs[].projects[].name	string	—	Project name
orgs[].projects[].pat	string	—	Personal Access Token
orgs[].projects[].safetyLevel	string	—	Safety level override for this specific project
defaultOrg	string	first org	Default organization
defaultProject	string	first project	Default project
defaultTeam	string	—	Default team
authMethod	string	"auto"	"pat", "azure-cli", or "auto"
safetyLevel	string	"confirm"	Global default: "open", "confirm", or "readonly"
defaultWorkItemType	string	"User Story"	Default type for creation
maxQueryResults	number	100	Max WIQL query results
autocomplete	boolean	true	Enable #id work item completion
mock	boolean	false	Use fixture data offline

Safety Levels

Level	Behavior
open	No confirmation on mutations
confirm	User confirms before create/update/delete
readonly	All mutation tools blocked

Safety level is resolved with cascading overrides — the most specific setting wins:

project.safetyLevel  >  org.safetyLevel  >  global safetyLevel  >  default ("confirm")

Example: set "open" globally so most projects flow freely, then lock down production with "readonly" on a specific project:

{
  "safetyLevel": "open",
  "orgs": [{
    "name": "my-org",
    "url": "https://dev.azure.com/my-org",
    "projects": [
      { "name": "DevProject", "pat": "..." },
      { "name": "ProdProject", "pat": "...", "safetyLevel": "readonly" }
    ]
  }]
}

Architecture

The extension follows a modular architecture:

• src/config/index.ts — Configuration management from pi-azure-devops.json
• src/auth/ — PAT and Azure CLI authentication
• src/tools/*.ts — 52 individual tool definitions
• src/extension/index.ts — Extension entry point, tool registration, safety interceptor
• src/utils/ — Connection factory, error handling, formatting
• src/autocomplete/ — #id and @sprint autocomplete providers
• src/safety/ — Mutation safety gates
• src/mocks/ — Offline fixture data and mock handler
• skills/ — Agent skill reference documentation
• prompts/ — 14 prompt templates for common workflows

Extensions Made

This package is forked from jwayong/pi-azure-devops with the following additions:

• index.ts entry point — Root-level entry point re-exporting the extension for pi package loading (was missing from original)
• azure-devops-doctor prompt template — New /azure-devops-doctor command for connection health checks
• GitHub Actions CI/CD — Continuous integration (typecheck, test, coverage) and automated semantic release workflows
• azure_devops_doctor tool — Built-in but fully validated and documented

Requirements

• Node.js 20.12+
• pi coding agent 0.70.0+
• Azure DevOps organization with PAT access

Dependencies

• azure-devops-node-api — Azure DevOps REST API client
• typebox — Runtime type validation

Publishing as a pi Package

To publish this extension to the pi package catalog:

1. Ensure package.json has "keywords": ["pi-package"]
2. Ensure package.json has a "pi" section declaring extensions, skills, and prompts
3. Optionally add "image" or "video" preview URLs to the "pi" manifest
4. Publish to npm: npm publish
5. Users install with: pi install npm:@patimweb/pi-azure-devops

The package catalog auto-discovers packages with the pi-package keyword from npm.

CI/CD

Continuous Integration (.github/workflows/ci.yml)

Runs on every push and PR to main/master:

• Matrix testing across Node.js 18, 20, 22
• Type checking (npm run typecheck)
• Unit tests (npm test)
• Coverage reporting to Codecov (Node 22 only)

Automated Release (.github/workflows/release.yml)

Runs on pushes to main and next branches:

• Builds the package (npm run build)
• Runs semantic-release for automated versioning and npm publishing
• Requires GITHUB_TOKEN and NPM_TOKEN secrets

License

MIT