omc-ado-setup

name	omc-ado-setup
description	Configure Azure DevOps integration for the current project. WHEN: User wants to set up ADO integration, connect a project to Azure DevOps, configure .omcp/config.json for ADO, or troubleshoot ADO connection issues. DO NOT USE FOR: Work item triage (use omc-ado-triage), sprint planning (use omc-ado-sprint), PR review (use omc-ado-review), or Azure cloud service configuration (use azure-skills plugin).
role	config-writer
scope	.omcp/**

OMC ADO Setup

Configure Azure DevOps integration for the current project. Detects the ADO org and project from the git remote URL, verifies authentication, and writes .omcp/config.json with all required settings.

When this skill is invoked, immediately execute the workflow below. Do not only restate or summarize these instructions back to the user.

Trigger Patterns

• "setup ado"
• "configure azure devops"
• "ado setup"
• "connect to azure devops"
• "omc-ado-setup"

Prerequisites

Before running the main workflow, verify all prerequisites are present. If any fail, report the issue and stop with actionable remediation steps.

Check 1: az CLI installed

az --version 2>&1 | head -1

If this fails: tell the user to install the Azure CLI from https://aka.ms/installazurecli.

Check 2: azure-devops extension installed

az extension show --name azure-devops --query name -o tsv 2>&1

If output is not azure-devops: run az extension add --name azure-devops to install it.

Check 3: az authentication status

az account show --query "{name:name, id:id, tenantId:tenantId}" -o json 2>&1

If this fails or returns an error: tell the user to run az login and retry.

Check 4: az devops configured defaults

az devops configure --list 2>&1

Show the output to the user so they can see existing defaults (org, project).

---

Step 1: Detect ADO Remote

Inspect the git remote URL to determine if the repo is hosted on Azure DevOps.

git remote -v 2>&1

Azure DevOps remote URLs follow these patterns:

• https://dev.azure.com/{org}/{project}/_git/{repo}
• https://{org}.visualstudio.com/{project}/_git/{repo}
• [e-mail]:v3/{org}/{project}/{repo}

Parse the remote URL to extract:

• org — the ADO organization name
• project — the ADO project name
• repo — the repository name

If no ADO remote is detected, inform the user and ask whether they want to configure manually (prompt for org, project, repo values).

---

Step 2: Probe Existing Configuration

Check if .omcp/config.json already exists:

cat .omcp/config.json 2>/dev/null || echo "NOT_FOUND"

If it exists and contains ado settings, ask the user whether to update or keep the existing configuration (use AskUserQuestion).

---

Step 3: Verify ADO Connection

Confirm the detected org and project are accessible with the current authentication:

az devops project show --project "{project}" --org "https://dev.azure.com/{org}" --query "{id:id, name:name, state:state}" -o json 2>&1

If this fails, the user may need to configure their PAT or re-authenticate:

# Option: configure a PAT
az devops configure --defaults organization=https://dev.azure.com/{org}

---

Step 4: Discover Optional Settings

Ask the user (via AskUserQuestion) for optional configuration. Defaults are shown in brackets.

Question: "Configure optional ADO settings? (Press Enter to accept defaults)"

For each item, probe the available values from ADO to help the user choose:

Work Item Type

az boards work-item type list --project "{project}" --org "https://dev.azure.com/{org}" --query "[].name" -o tsv 2>&1

Common values: User Story, Bug, Task, Issue. Default: User Story.

Area Path

az boards area project list --project "{project}" --org "https://dev.azure.com/{org}" --query "children[].path" -o tsv 2>&1

Default: {project} (root area).

Iteration Path

az boards iteration project list --project "{project}" --org "https://dev.azure.com/{org}" --query "children[].path" -o tsv 2>&1

Default: {project} (root iteration, i.e. no sprint filter).

---

Step 5: Write .omcp/config.json

Create or update the config file. Preserve any existing non-ADO keys.

First, ensure the .omcp/ directory exists:

mkdir -p .omcp

Write .omcp/config.json using the Write (or Edit) tool. The schema is:

{
  "ado": {
    "org": "https://dev.azure.com/{org}",
    "project": "{project}",
    "repo": "{repo}",
    "workItemType": "User Story",
    "areaPath": "{project}",
    "iterationPath": "{project}",
    "configuredAt": "{ISO timestamp}"
  }
}

Configuration Schema Reference

Key	Type	Description
ado.org	string	Full org URL: https://dev.azure.com/{org}
ado.project	string	ADO project name (case-sensitive)
ado.repo	string	ADO repository name
ado.workItemType	string	Default work item type for queries (e.g. User Story)
ado.areaPath	string	Area path filter (e.g. MyProject\TeamA)
ado.iterationPath	string	Iteration path filter (e.g. MyProject\Sprint 5)
ado.configuredAt	string	ISO 8601 timestamp of when setup ran

Example output

{
  "ado": {
    "org": "https://dev.azure.com/contoso",
    "project": "Widgets",
    "repo": "widgets-api",
    "workItemType": "User Story",
    "areaPath": "Widgets\\Backend",
    "iterationPath": "Widgets\\Sprint 22",
    "configuredAt": "2026-03-09T12:00:00Z"
  }
}

---

Step 6: Verify Connection

Run a smoke test by listing the most recent 5 work items assigned to the current user:

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.TeamProject] = '{project}' ORDER BY [System.ChangedDate] DESC" --project "{project}" --org "https://dev.azure.com/{org}" -o table 2>&1 | head -20

If the query returns results: report success and show the items. If the query fails with an auth error: suggest az login or PAT configuration. If the query returns 0 items: that is normal — confirm setup is complete.

---

Step 7: Report and Next Steps

Report a summary of what was configured:

ADO Setup Complete

Organization : https://dev.azure.com/{org}
Project      : {project}
Repository   : {repo}
Work Item Type: {workItemType}
Area Path    : {areaPath}
Iteration    : {iterationPath}
Config file  : .omcp/config.json

Next steps:
  /oh-my-copilot:omc-ado-triage   — run a full triage of work items and PRs

---

Error Reference

Error	Likely cause	Fix
az: command not found	Azure CLI not installed	Install from https://aka.ms/installazurecli
ERROR: Please run 'az login'	Not authenticated	Run az login
Extension 'azure-devops' not installed	Missing extension	Run az extension add --name azure-devops
ResourceNotFound on project show	Wrong org/project	Verify the remote URL and re-run
TF400813: Resource not available	PAT missing or expired	Create a PAT in ADO → User Settings → Personal Access Tokens