omc-ado-setup

Set up or troubleshoot the Azure DevOps integration for this project (.omg/config.json connection). Not for triage, sprint planning, PR review, Azure cloud service config, or GitHub repos (omc-gh-setu

SKILL.md

GitHub

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 .omg/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}
  • git@ssh.dev.azure.com: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 .omg/config.json already exists:

node -e "const f=require('fs');try{process.stdout.write(f.readFileSync('.omg/config.json','utf8'))}catch{console.log('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 .omg/config.json

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

First, ensure the .omg/ directory exists:

node -e "require('fs').mkdirSync('.omg',{recursive:true});console.log('Ensured .omg/')"

Write .omg/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  : .omg/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