Azure DevOps

Why this guide is mostly about vocabulary

Azure DevOps is the second tool that needs no code-host declaration: Boards and Repos are the same product, so the backlog and the pull request live together and the optional split introduced by ADR-018 resolves to the zero-configuration path, omit the field and the code host is the PM tool (Code host vs PM tool states the routing rule).

The friction here is a different one, and it is the reason this page carries a State Mapping section the GitHub guide does not need. pair's skills reason in five canonical macrostates (Draft, Ready, In Progress, Review, Done): an internal vocabulary, so a skill never has to know your board's column names.

Azure Boards has its own vocabulary and it is not that one: a Scrum process's forward flow is New / Approved / Committed / Done (Agile's is New / Active / Resolved / Closed; both also ship Removed, which is off that flow, see State Mapping), and none of them is a review state. The mapping below assumes one was added, see the note under the table for how.

The naive fix (teach each skill Azure's words) would have to be repeated in every skill and redone for every custom process.

So the mapping is declared once, in your adoption file, and skills read and write board state exclusively through it. The same reasoning covers the work item types: pair's Initiative → Epic → Story → Task ladder is mapped onto Azure's Epic → Feature → PBI → Task rather than assumed, which is what lets an Agile process (User Story instead of Product Backlog Item) or a custom process work by overriding a table instead of patching pair.

One consequence you inherit from Azure's model: board membership here is implicit: a work item belongs to its team project the moment it is created, so there is no "add it to the board" step.

What decides whether your team actually sees it is the area path: a work item whose area falls outside the ones your team's board is configured for is created, assigned, and invisible. pair therefore passes --area on every create rather than accepting the project default (per the pm-adapter-visibility-contract decision record: an adapter with implicit membership must still name the field that decides the read view).

Configuration

Add these lines to .pair/adoption/tech/way-of-working.md:

- Azure DevOps is adopted for project management.
  Organization: <org>. Project: <project>.
  Team: <team>. Area path: <area-path>.
  See `.pair/knowledge/guidelines/collaboration/project-management-tool/azure-devops-implementation.md` for usage.

Team and Area path are what every work item create passes as --area. Skip them and items land outside the area paths your team's board is configured for, created, assigned, and missing from the board you actually look at.

Prerequisites

• Azure DevOps organization and project (https://dev.azure.com/<org>/<project>)
• Azure CLI (az) with the azure-devops extension installed
• Authenticated session (az login or a PAT via az devops login)

az extension add --name azure-devops
az devops configure --defaults organization=https://dev.azure.com/<org> project=<project>

pair's AI assistants operate on work items via az boards and on pull requests via az repos. If the CLI is missing or unauthenticated, skills stop and point you to the setup steps: they never install or log in on their own.

Mapping Model

pair maps its work hierarchy to Azure Boards work item types (Scrum process shown; Agile uses User Story instead of PBI):

pair                    Azure Boards
────                    ────────────
Initiative          →   Epic
Epic                →   Feature
User Story          →   Product Backlog Item
Task                →   Task

How It Works

• Initiatives are Epics on the Epics backlog level
• Epics are Features, children of their initiative
• User Stories are Product Backlog Items, children of their feature
• Tasks are Task work items nested under the story on the sprint Taskboard
• Hierarchy uses native parent-child relations (az boards work-item relation add)
• Custom process with renamed types? Override the mapping table in way-of-working.md

State Mapping

Azure Boards states rarely match pair's canonical states (Draft, Ready, In Progress, Review, Done). Declare the mapping once in way-of-working.md:

## State Mapping
 
| Board State | Macrostate  |
| ------------ | ----------- |
| New          | Draft       |
| Approved     | Ready       |
| Committed    | In Progress |
| In Review    | Review      |
| Done         | Done        |

Skills read and write board states exclusively through this map. Extra states can stay unmapped, pair ignores them, and board columns never enter the map at all.

Removed (stock in both the Scrum and the Agile process) is the example of a state deliberately left out of the table. pair's five macrostates exist so a skill can decide something, and a removed item asks nothing of any skill, so there is no sixth macrostate to map it onto (canonical-states.md records this). A Removed item is read as unmapped and ignored rather than mistaken for Done, and the guide's own backlog queries exclude it (AND [System.State] <> 'Removed').

The example above assumes a Scrum process to which an In Review state was added through an inherited process, route (a) in canonical-states.md, Example 5.

No out-of-box Azure process ships one, and a board column cannot stand in for it: System.BoardColumn only labels a visual bucket inside an existing state, and az boards work-item update --state cannot target it.

If you would rather not add a state, take route (b) and map Review to an existing one such as Committed; either way, map Review only to a state your process actually defines, writing one it does not is rejected by Azure.

Status Transitions

Priority and Fields

First-Run Example

After configuring way-of-working.md, run a process skill:

/pair-process-plan-stories #42    # break feature #42 into stories

Expected output:

STORIES CREATED:
├── PBI 101: As a user, I want to sign up so that I can access the platform
├── PBI 102: As a user, I want to log in so that I can see my dashboard
├── PBI 103: As a user, I want to reset my password so that I can recover access
└── Feature 42: 3 stories created, all in "New"

pair creates Product Backlog Items as children of the feature, sets priority, and places them on your board.

Verifying the Setup

1. Open Boards → Backlogs → Backlog items
2. Verify new PBIs appear in the Draft-mapped state ("New")
3. Each PBI should show its parent feature
4. Priority and tags should match pair's configuration

Related

• PM Tools overview: choosing the right tool
• Filesystem: zero-PM-dependency alternative (backlog in your repo; still declares a code-host)
• GitHub Projects: GitHub-native option
• Linear: dedicated PM tool option